Make text-quoting-style customizable. Introduce t and new meaning for nil.

A value of nil for text-quoting-style now means "no translation".  t means
"Use curved quotes if displayable".

* src/doc.c (text-quoting-style (function)): modify for new semantics.
(text-quoting-style (variable)): Amend the doc string, set the default value
to t.

* lisp/cus-start.el: (top level): Create a customize entry for
text-quoting-style in group display.

* etc/NEWS: Amend the entry for text-quoting-style.

* doc/emacs/display.texi (Text Display): Describe the translation of ASCII
quotes to curved quotes, and how to influence or inhibit it.

* doc/lispref/control.texi (Signalling Errors)
* doc/lispref/display.texi (Displaying Messages)
* doc/lispref/strings.texi (Formatting Strings): Describe binding
text-quoting-style to nil to inhibit unwanted quote translation.

* doc/lispref/help.texi (Keys in Documentation): Change text-quoting-style
from a variable to a user option.  Describe its changed set of values.  State
that it can be customized freely.

5 files changed, 38 insertions, 21 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 6afd8366b25..5860bacb9d8 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1548,11 +1548,20 @@ for details.
 @cindex curly quotes
 @cindex curved quotes
 @cindex homoglyph face
+
+Emacs tries to determine if the curved quotes @samp{‘} and @samp{’}
+can be displayed on the current display.  By default, if this seems to
+be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`}
+and @samp{'}), when they appear in messages and help texts, to these
+curved quotes.  You can influence or inhibit this translation by
+customizing the user option @code{text-quoting-style} (@pxref{Keys in
+Documentation,,, elisp, The Emacs Lisp Reference Manual}).
+
   If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are
 known to look just like @acronym{ASCII} characters, they are shown
-with the @code{homoglyph} face.  Curved quotes that cannot be
-displayed are shown as their @acronym{ASCII} approximations @samp{`},
-@samp{'}, and @samp{"} with the @code{homoglyph} face.
+with the @code{homoglyph} face.  Curved quotes that are known not to
+be displayable are shown as their @acronym{ASCII} approximations
+@samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face.
 
 @node Cursor Display
 @section Displaying the Cursor
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf23..09435f57966 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1108,6 +1108,9 @@ generates a message like @t{"Missing ‘foo’"} with matching curved
 quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
 with only apostrophes typically generates a message like @t{"Missing
 ’foo’"} with only closing curved quotes, an unusual style in English.
+One way around this problem is to bind @code{text-quoting-style} to
+@code{nil} around the call to @code{error}; this causes the
+@acronym{ASCII} quote characters to be output unchanged.
 
 @strong{Warning:} If you want to use your own string as an error message
 verbatim, don't just write @code{(error @var{string})}.  If @var{string}
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3dae984f339..8f58fca506f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -272,6 +272,9 @@ generates a message like @t{"Missing ‘foo’"} with matching curved
 quotes.  In contrast, a call using a format like @t{"Missing '%s'"}
 with only apostrophes typically generates a message like @t{"Missing
 ’foo’"} with only closing curved quotes, an unusual style in English.
+One way around this problem is to bind @code{text-quoting-style} to
+@code{nil} around calls to @code{message}; this causes the
+@acronym{ASCII} quote characters to be output unchanged.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index cb214113523..e1e98124e08 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -351,25 +351,24 @@ and @samp{\=\=} puts @samp{\=} into the output.
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defvar text-quoting-style
+@defopt text-quoting-style
 @cindex curved quotes
 @cindex curly quotes
 The value of this variable is a symbol that specifies the style Emacs
-should use for single quotes in the wording of help and messages.
-If the variable's value is @code{curve}, the style is
-@t{‘like this’} with curved single quotes.  If the value is
-@code{straight}, the style is @t{'like this'} with straight
-apostrophes.  If the value is @code{grave},
-quotes are not translated and the style is @t{`like
-this'} with grave accent and apostrophe, the standard style
-before Emacs version 25.  The default value @code{nil}
-acts like @code{curve} if curved single quotes are displayable, and
-like @code{grave} otherwise.
-
-This variable can be used by experts on platforms that have problems
-with curved quotes.  As it is not intended for casual use, it is not a
-user option.
-@end defvar
+should use for single quotes in the wording of help and messages.  If
+the variable's value is @code{curve}, the style is @t{‘like this’}
+with curved single quotes.  If the value is @code{straight}, the style
+is @t{'like this'} with straight apostrophes.  If the value is
+@code{nil} or @code{grave}, quotes are not translated and the style is
+@t{`like this'} with grave accent and apostrophe, the standard style
+before Emacs version 25.  The default value @code{t} acts like
+@code{curve} if curved single quotes seem to be displayable, and like
+@code{nil} otherwise.
+
+This option is useful on platforms that have problems with curved
+quotes.  You can customize it freely according to your personal
+preference.
+@end defopt
 
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 219225d412b..117a373a190 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -835,8 +835,11 @@ A format that quotes with grave accents and apostrophes @t{`like
 this'} typically generates curved quotes @t{‘like this’}.  In
 contrast, a format that quotes with only apostrophes @t{'like this'}
 typically generates two closing curved quotes @t{’like this’}, an
-unusual style in English.  @xref{Keys in Documentation}, for how the
-@code{text-quoting-style} variable affects generated quotes.
+unusual style in English.  One way around such problems is to bind
+@code{text-quoting-style} to @code{nil} around calls to
+@code{format-message}; this causes the @acronym{ASCII} quoting
+characters to be output unchanged.  @xref{Keys in Documentation}, for
+how the @code{text-quoting-style} variable affects generated quotes.
 @end defun
 
 @cindex @samp{%} in format