Re: Emacs 26.1 release branch created

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

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

On 09/25/2017 12:03 PM, Alan Mackenzie wrote:
> At the moment, there is a single known example in the Emacs lisp code

There are plenty of examples other than the one you noticed in 
cc-engine.el. For example, here's one in shell.el's 
shell-dirstack-message function:

    (message "%s" msg)

MSG is a string containing directory names followed by spaces, and the 
"%s" avoids translation of directory names that happen to contain grave 
accents or apostrophes (or percents, for that matter). This is a common 
programming technique in Emacs source code, and has been for decades.

> I will be unhappy if the text around the cross references
> doesn't state that the translation of quotes can be inhibited.  Without
> that, the documentation of each function would be incomplete and
> fragmented.  "To influence or inhibit this translation of the quote
> characters, see xxxxxx." would do.

Sure, that's easy. Revised patch attached.

> How about merging this change into emacs-26 anyway, now?

I now see one minor error in the scratch/customize-quotes patch, which 
is that its etc/NEWS file incorrectly states ", except that 
'text-quoting-style' no longer affects the treatment of curved quotes in 
format arguments to functions like 'message' and 'format-message'", a 
phrase that appears to be a stray leftover from an earlier version of 
your proposal. The attached patch fixes that, and also has been rebased 
to apply after the scratch/customize-quotes is merged in, so I suggest 
that you merge scratch/customize-quotes and that I then apply the 
attached patch.

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

From 61d118e52b971300ecec5e0a5e404631d51e372e Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 25 Sep 2017 16:29:51 -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.
* etc/NEWS: text-quoting-style semantics have not changed.
---
 doc/lispref/control.texi | 14 +++--------
 doc/lispref/display.texi | 16 ++++--------
 doc/lispref/elisp.texi   |  1 +
 doc/lispref/help.texi    | 64 ++++++++++++++++++++++++++++++++++--------------
 doc/lispref/strings.texi | 15 +++---------
 doc/lispref/tips.texi    |  4 +--
 etc/NEWS                 |  6 ++---
 7 files changed, 63 insertions(+), 57 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index c39e035459..4eddbe9c12 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1101,16 +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.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around the call to @code{error}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+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 influence
+or inhibit 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 62b136f6c6..afd09cfb33 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,16 +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.
-One way around this problem is to bind @code{text-quoting-style} to
-the symbol @code{grave} around calls to @code{message}; this causes
-@acronym{ASCII} quote characters to be output unchanged.
+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 influence
+or inhibit this translation.
 
 In batch mode, the message is printed to the standard error stream,
 followed by a newline.
@@ -7038,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 74dc6dac9c..5fc18785b6 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,25 +353,6 @@ Keys in Documentation
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@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 seem to be displayable, and like @code{grave}
-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
 replaces them by what they stand for, returning the result as a string.
@@ -428,6 +411,49 @@ 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.
+@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 10385e0550..1fb1a0e148 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -826,21 +826,14 @@ 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.  One way around such problems is to bind
-@code{text-quoting-style} to the symbol @code{grave} around calls to
-@code{format-message}; this causes @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
+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 influence
+or inhibit this translation.
 
 @cindex @samp{%} in format
 @cindex format specification
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index bed3bed95b..73b5224bc3 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -680,8 +680,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
diff --git a/etc/NEWS b/etc/NEWS
index 755893b9b5..634a3600d1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1234,10 +1234,8 @@ change FOO, respectively.  The exhaustive list of removed variables 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.  Its possible values and their semantics remain unchanged
-from Emacs 25, except that '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.
+from Emacs 25.  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'
-- 
2.13.5