Re: Emacs 26.1 release branch created

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 1052 bytes --]

On 09/22/2017 11:04 AM, Alan Mackenzie wrote:
> the main point here is to remind the reader that quotes can be
> output as is by binding text-quoting-style

But that's not how Elisp code typically outputs quotes as is. I see no 
instances of such a thing in the emacs-26 branch. Instead, code 
typically uses backslash escapes (in doc strings) or %s applied to the 
output of 'format' (in message formats). It's better for the Elisp 
manual to suggest the techniques that are typically used.

> Perhaps you could suggest an improved wording
Sure, a suggested patch is attached. This patch attempts to address only 
this issue; it doesn't affect whether text-quoting-style is 
customizable, as that is orthogonal. Since there were three or four 
copies of boilerplate language that was getting longer, this patch 
creates a new node Text Quoting Style that contains the detailed 
discussion of text-quoting-style and how to get around it, and adjusts 
the other parts of the manual to mention the issue briefly and 
cross-reference to the new section.


[-- Attachment #2: 0001-Improve-text-quoting-style-doc-in-lispref.txt --]
[-- Type: text/plain, Size: 11311 bytes --]

From dd9535349f18346f85f9f40940451a0b20f3897c Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 22 Sep 2017 13:29:17 -0700
Subject: [PATCH] Improve text-quoting-style doc in lispref

* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages.  Adjust xrefs to point to this section
when appropriate.
---
 doc/lispref/control.texi | 10 +++----
 doc/lispref/display.texi | 12 ++++-----
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 69 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 12 ++++-----
 doc/lispref/tips.texi    |  4 +--
 6 files changed, 66 insertions(+), 42 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf2..ffa6b59f49 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,13 +1101,11 @@ Signaling Errors
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
+@vindex text-quoting-style
 The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-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.
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 
 @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 3dae984f33..2322766945 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,13 +265,11 @@ Displaying Messages
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
+@vindex text-quoting-style
 The @code{text-quoting-style} variable controls what quotes are
-generated; @xref{Keys in Documentation}.  A call using a format like
-@t{"Missing `%s'"} with grave accents and apostrophes typically
-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.
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7035,7 +7033,7 @@ Active Display Table
 is outputting text to the standard output or error streams.  Although its
 default is typically @code{nil}, in an interactive session if the
 terminal cannot display curved quotes, its default maps curved quotes
-to ASCII approximations.  @xref{Keys in Documentation}.
+to ASCII approximations.  @xref{Text Quoting Style}.
 @end defvar
 
 The @file{disp-table} library defines several functions for changing
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 4cbcdf855d..c752594584 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -940,6 +940,7 @@ Top
 * Documentation Basics::    Where doc strings are defined and stored.
 * Accessing Documentation:: How Lisp programs can access doc strings.
 * Keys in Documentation::   Substituting current key bindings.
+* Text Quoting Style::      Quotation marks in doc strings and messages.
 * Describing Characters::   Making printable descriptions of
                               non-printing characters and key sequences.
 * Help Functions::          Subroutines used by Emacs help facilities.
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index cb21411352..c3cc5a98a6 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -33,6 +33,7 @@ Documentation
 * Documentation Basics::      Where doc strings are defined and stored.
 * Accessing Documentation::   How Lisp programs can access doc strings.
 * Keys in Documentation::     Substituting current key bindings.
+* Text Quoting Style::        Quotation marks in doc strings and messages.
 * Describing Characters::     Making printable descriptions of
                                 non-printing characters and key sequences.
 * Help Functions::            Subroutines used by Emacs help facilities.
@@ -336,6 +337,7 @@ Keys in Documentation
 (grave accent) stands for a left quote.
 This generates a left single quotation mark, an apostrophe, or a grave
 accent depending on the value of @code{text-quoting-style}.
+@xref{Text Quoting Style}.
 
 @item '
 (apostrophe) stands for a right quote.
@@ -351,26 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defvar 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
-
 @defun substitute-command-keys string
 This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
@@ -429,6 +411,53 @@ Keys in Documentation
 strings---for instance, you can refer to functions, variables, and
 sections of this manual.  @xref{Documentation Tips}, for details.
 
+@node Text Quoting Style
+@section Text Quoting Style
+
+  Typically, grave accents and apostrophes are treated specially in
+documentation strings and diagnostic messages, and generate matching
+single quotation marks (also called ``curved quotes'').  For example,
+the documentation string @t{"Alias for `foo'."} and the function call
+@code{(message "Alias for `foo'.")} both generate @t{"Alias for
+‘foo’."}.  Less commonly, Emacs displays grave accents and apostrophes
+as themselves, or as apostrophes only (e.g., @t{"Alias for 'foo'."}).
+Documentation strings and message formats should be written so that
+they display well with any of these styles.  For example, the
+documentation string @t{"Alias for 'foo'."} is probably not what you
+want, as it can display as @t{"Alias for ’foo’."}, an unusual style in
+English.
+
+  Sometimes you may need to display a grave accent or apostrophe
+without translation, regardless of text quoting style.  In a
+documentation string, you can do this with escapes.  For example, in
+the documentation string @t{"\\=`(a ,(sin 0)) ==> (a 0.0)"} the grave
+accent is intended to denote Lisp code, so it is escaped and displays
+as itself regardless of quoting style.  In a call to @code{message} or
+@code{error}, you can avoid translation by using a format @t{"%s"}
+with an argument that is a call to @code{format}.  For example,
+@code{(message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x)))}
+displays a message that starts with grave accent regardless of text
+quoting style.
+
+@defvar 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
+
 @node Describing Characters
 @section Describing Characters for Help Messages
 @cindex describe characters and events
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 219225d412..09434ce573 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,17 +826,15 @@ Formatting Strings
 @defun format-message string &rest objects
 @cindex curved quotes, in formatted messages
 @cindex curly quotes, in formatted messages
-@cindex @code{text-quoting-style}, and formatting messages
 This function acts like @code{format}, except it also converts any
 grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the
 value of @code{text-quoting-style}.
 
-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.
+@vindex text-quoting-style
+The @code{text-quoting-style} variable controls what quotes are
+generated.  Typically grave accent and apostrophe in the format
+generate matching curved quotes, e.g., @t{"Missing `%s'"} might
+generate @t{"Missing ‘foo’"}.  @xref{Text Quoting Style}.
 @end defun
 
 @cindex @samp{%} in format
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 17fd4a1027..0bccde66cd 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -683,8 +683,8 @@ Documentation Tips
 older convention was designed for now-obsolete displays in which grave
 accent and apostrophe were mirror images.
 Documentation using this convention is converted to the user's
-preferred format when it is copied into a help buffer.  @xref{Keys in
-Documentation}.
+preferred format when it is copied into a help buffer.  @xref{Text
+Quoting Style}.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-- 
2.13.5