Re: Emacs 26.1 release branch created

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

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

Alan Mackenzie wrote:

> Putting a single output
> operation through two `format'-like operations is bizarre and
> extravagant.  It's not something we should encourage.

It's not bizarre; it's routine in Emacs Lisp code. And it's not extravagant: the 
loss in efficiency for messages is tiny, and is not something users have noticed 
or complained about.

> By contrast, binding a controlling variable around an operation is the
> standard Emacs way of doing such things.

It's standard for other things, but it's definitely not standard here. The Emacs 
source code never does it this way.

> How many such instances are there in the code anyway?

There are about 400 instances of '(message "%s"' or '(error "%s"' in the Emacs 
source code. For decades this has been common practice when an Elisp programmer 
wants to avoid translation or formatting in the argument to 'message'-like 
functions. It's not that easy to count how many of the 400 instances are for 
quotes as opposed to being for other things, but I'd guess dozens.

> This would need fleshing out with something like "To inhibit
> or influence this translation of ASCII quotes, see text-quoting-style".

Sure, that's easy. Revised proposal attached.

> The "boilerplate" you want to replace is short and to the point,

It is not short; it's discursive and it gets in the way. In your proposal, it's 
about ten lines of boilerplate for each affected function, boilerplate that is 
about as long as the main function description itself. We should move most of 
this boilerplate to a common section, and briefly allude to it in each affected 
function. This will give us room to expand on the issue in the common section, 
which I've done in my proposal - it has about twenty lines discussing the issue, 
and this is shorter and provides more useful info than repeating ten lines in 
multiple places.

> A further general point about this bit of doc is its rather strange use
> of the verb "generate".

Also easy; the revised proposal (attached) uses "translates to" instead of 
"generates".

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-text-quoting-style-doc-in-lispref.patch --]
[-- Type: text/x-patch; name="0001-Improve-text-quoting-style-doc-in-lispref.patch", Size: 11498 bytes --]

From 8bc41bd77d272e2273e4f40cf7b4a57fe8900045 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 24 Sep 2017 11:02:40 -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 | 11 +++-----
 doc/lispref/display.texi | 13 ++++-----
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 69 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 12 +++------
 doc/lispref/tips.texi    |  4 +--
 6 files changed, 65 insertions(+), 45 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 401a999cf2..ab0b49266d 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,13 +1101,10 @@ Signaling Errors
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
-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.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 
 @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..12ca065d86 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,13 +265,10 @@ Displaying Messages
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
-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.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7035,7 +7032,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..3da365904e 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 translate to 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 translate to @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..a89e9671d7 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,17 +826,13 @@ 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.
+Typically grave accent and apostrophe in the format translate to
+matching curved quotes, e.g., @t{"Missing `%s'"} might result in
+@t{"Missing ‘foo’"}.  @xref{Text Quoting Style}, for how to control
+this translation.
 @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