[Emacs-diffs] emacs-26 d5e4e00 1/4: Make text-quoting-style customizable. Introduce t and new meaning for nil.

[Alan Mackenzie]

branch: emacs-26
commit d5e4e004fa134cb81989bcf40c5d6c79b837301f
Author: Alan Mackenzie <address@hidden>
Commit: Alan Mackenzie <address@hidden>

    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.
---
 doc/emacs/display.texi   | 15 ++++++++++++---
 doc/lispref/control.texi |  3 +++
 doc/lispref/display.texi |  3 +++
 doc/lispref/help.texi    | 31 +++++++++++++++----------------
 doc/lispref/strings.texi |  7 +++++--
 etc/NEWS                 | 13 +++++++++----
 lisp/cus-start.el        |  9 +++++++++
 src/doc.c                | 36 ++++++++++++++++++++----------------
 8 files changed, 76 insertions(+), 41 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index 6afd836..5860bac 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{`},
address@hidden'}, 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
address@hidden, @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 401a999..09435f5 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
address@hidden around the call to @code{error}; this causes the
address@hidden 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 3dae984..8f58fca 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
address@hidden around calls to @code{message}; this causes the
address@hidden 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 cb21411..e1e9812 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.
 
address@hidden text-quoting-style
address@hidden 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
address@hidden this’} with curved single quotes.  If the value is
address@hidden, 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.
address@hidden 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
address@hidden or @code{grave}, quotes are not translated and the style is
address@hidden this'} with grave accent and apostrophe, the standard style
+before Emacs version 25.  The default value @code{t} acts like
address@hidden if curved single quotes seem to be displayable, and like
address@hidden otherwise.
+
+This option is useful on platforms that have problems with curved
+quotes.  You can customize it freely according to your personal
+preference.
address@hidden 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 219225d..117a373 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
address@hidden variable affects generated quotes.
+unusual style in English.  One way around such problems is to bind
address@hidden to @code{nil} around calls to
address@hidden; 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
diff --git a/etc/NEWS b/etc/NEWS
index 2216cfc..d518d5e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1244,10 +1244,15 @@ change FOO, respectively.  The exhaustive list of 
removed variables is:
 *** Many variables obsoleted in 22.1 referring to face symbols
 
 +++
-** The variable 'text-quoting-style' no longer affects the treatment
-of curved quotes in format arguments to functions like 'message' and
-'format-message'.  In particular, when this variable's value is
-'grave', all quotes in formats are output as-is.
+** The variable `text-quoting-style' is now a customizable option.  It
+controls whether to and how to translate ASCII quotes in messages and
+help output.  The value nil now means "no translation", and the value
+t, the default, means "use curved quotes if displayable" (as nil did
+in Emacs 25).  The other possible values remain unchanged.
+`text-quoting-style' no longer affects the treatment of curved quotes
+in format arguments to functions like `message' and `format-message'.
+In particular, when this variable's value is `grave', all quotes in
+formats are output as-is.
 
 ---
 ** Functions like 'check-declare-file' and 'check-declare-directory'
diff --git a/lisp/cus-start.el b/lisp/cus-start.el
index fd015b7..f5e1431 100644
--- a/lisp/cus-start.el
+++ b/lisp/cus-start.el
@@ -223,6 +223,15 @@ Leaving \"Default\" unchecked is equivalent with 
specifying a default of
             (visible-bell display boolean)
             (no-redraw-on-reenter display boolean)
 
+             ;; doc.c
+             (text-quoting-style display
+                                 (choice
+                                  (const :tag "No translation" nil)
+                                  (const :tag "Prefer \\=‘curved\\=’ quotes, 
if possible" t)
+                                  (const :tag "\\=‘Curved\\=’ quotes" curved)
+                                  (const :tag "\\='Straight\\=' quotes" 
straight)
+                                  (const :tag "\\=`Grave\\=' quotes" grave)))
+
              ;; dosfns.c
             (dos-display-scancodes display boolean)
             (dos-hyper-key keyboard integer)
diff --git a/src/doc.c b/src/doc.c
index 3286c12..e2af39e 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -690,8 +690,9 @@ enum text_quoting_style
 text_quoting_style (void)
 {
   if (NILP (Vtext_quoting_style)
-      ? default_to_grave_quoting_style ()
-      : EQ (Vtext_quoting_style, Qgrave))
+      || (EQ (Vtext_quoting_style, Qt)
+          ? default_to_grave_quoting_style ()
+          : EQ (Vtext_quoting_style, Qgrave)))
     return GRAVE_QUOTING_STYLE;
   else if (EQ (Vtext_quoting_style, Qstraight))
     return STRAIGHT_QUOTING_STYLE;
@@ -1018,22 +1019,25 @@ syms_of_doc (void)
   Vbuild_files = Qnil;
 
   DEFVAR_LISP ("text-quoting-style", Vtext_quoting_style,
-               doc: /* Style to use for single quotes in help and messages.
-Its value should be a symbol.  It works by substituting certain single
-quotes for grave accent and apostrophe.  This is done in help output
-and in functions like `message' and `format-message'.  It is not done
-in `format'.
-
-`curve' means quote with curved single quotes ‘like this’.
-`straight' means quote with straight apostrophes \\='like this\\='.
-`grave' means quote with grave accent and apostrophe \\=`like this\\=';
-i.e., do not alter quote marks.  The default value nil acts like
-`curve' if curved single quotes are displayable, and like `grave'
-otherwise.  */);
-  Vtext_quoting_style = Qnil;
+               doc: /* How to translate single quotes in help and messages.
+Its value should be a symbol, and describes the style of quote
+substituted for ASCII quote characters GRAVE ACCENT (\\=`, \\=\\x60) and
+APOSTROPHE (\\=', \\=\\x27).  This is done in help output and in functions
+like `message' and `format-message'.  It is not done in `format'.
+
+The value nil means do not translate the quotes at all.  The value t
+(the default) acts like `curve' if curved single quotes appear to be
+displayable, and like nil otherwise.  `curve' means quote with curved
+single quotes ‘like this’.  `straight' means quote with apostrophes
+\\='like this\\='.  `grave' means do not translate quote marks and is
+now a synonym for nil.
+
+(The value t was newly introduced in Emacs 26, and in Emacs 25 nil
+meant what t means now.)  */);
+  Vtext_quoting_style = Qt;
 
   DEFVAR_BOOL ("internal--text-quoting-flag", text_quoting_flag,
-              doc: /* If nil, a nil `text-quoting-style' is treated as 
`grave'.  */);
+              doc: /* If nil, a `text-quoting-style' value t is treated as 
`nil'.  */);
   /* Initialized by ‘main’.  */
 
   defsubr (&Sdocumentation);