Extend ‘format’ to translate curved quotes

This is a followup to the recent doc string change, and deals with
diagnostics and the like.  This patch is more conservative than
the doc string change, in that the behavior of ‘format’ changes
only if its first arg contains curved quotes and the user prefers
straight or grave quotes.  (Come to think of it, perhaps we should
be similarly conservative with doc strings too, but that can wait.)
The upside of this conservatism is that existing usage is almost
surely unaffected.  The downside is that we'll eventually have to
change Emacs's format strings to use curved quotes in places where
the user might want curved quotes, but that's a simple and
mechanical translation that I'm willing to do later.  (Bug#21222)
* doc/lispref/help.texi (Keys in Documentation):
Move description of text-quoting-style from here ...
* doc/lispref/strings.texi (Formatting Strings):
... to here, and describe new behavior of ‘format’.
* etc/NEWS: Describe new behavior.
* lisp/calc/calc-help.el (calc-describe-thing):
* lisp/emacs-lisp/derived.el (derived-mode-make-docstring):
* lisp/info.el (Info-find-index-name):
Use ‘concat’ rather than ‘format’ to avoid misinterpretation
of recently-added curved quotes.
* src/doc.c (uLSQM0, uLSQM1, uLSQM2, uRSQM0, uRSQM1, uRSQM2):
Move from here ...
* src/lisp.h: ... to here.
* src/doc.c (text_quoting_style): New function.
(Fsubstitute_command_keys): Use it.
* src/editfns.c (Fformat): Implement new behavior.
* src/lisp.h (enum text_quoting_style): New enum.

2 files changed, 53 insertions, 32 deletions

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index ca8ae3f314a..ab1696e6712 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -347,19 +347,11 @@ 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
 @cindex curved quotes
 @cindex curly quotes
-The value of this variable specifies the style
+The value of the @code{text-quoting-style} variable specifies the style
 @code{substitute-command-keys} uses when generating left and right
-quotes.  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}, the style is @t{`like
-this'} with grave accent and apostrophe.  The default value @code{nil}
-acts like @code{curve} if curved single quotes are displayable, and
-like @code{grave} otherwise.
-@end defvar
+quotes.  @xref{Formatting Strings}, for more information.
 
 @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 c2f06079cb6..30933387b20 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -805,22 +805,27 @@ formatting feature described here; they differ from @code{format} only
 in how they use the result of formatting.
 
 @defun format string &rest objects
-This function returns a new string that is made by copying
+This function returns a string that is equivalent to copying
 @var{string} and then replacing any format specification
 in the copy with encodings of the corresponding @var{objects}.  The
 arguments @var{objects} are the computed values to be formatted.
 
 The characters in @var{string}, other than the format specifications,
 are copied directly into the output, including their text properties,
-if any.
+if any.  If the output equals @var{string}, this function may return
+@var{string} itself rather than a new copy.
 @end defun
 
 @cindex @samp{%} in format
 @cindex format specification
+@cindex curved quotes
+@cindex curly quotes
   A format specification is a sequence of characters beginning with a
-@samp{%}.  Thus, if there is a @samp{%d} in @var{string}, the
-@code{format} function replaces it with the printed representation of
-one of the values to be formatted (one of the arguments @var{objects}).
+@samp{%} or is a curved single quotation mark.  Except for @samp{%%}
+and quotation marks, each format specification says how to represent
+one of the arguments @var{objects}.  For example, if there
+is a @samp{%d} in @var{string}, the @code{format} function replaces it
+with the decimal representation of the integer to be formatted.
 For example:
 
 @example
@@ -830,11 +835,12 @@ For example:
 @end group
 @end example
 
-  Since @code{format} interprets @samp{%} characters as format
+  Since @code{format} interprets @samp{%}, @samp{‘} and @samp{’}
+characters as format
 specifications, you should @emph{never} pass an arbitrary string as
 the first argument.  This is particularly true when the string is
 generated by some Lisp code.  Unless the string is @emph{known} to
-never include any @samp{%} characters, pass @code{"%s"}, described
+never include any of the three special characters, pass @code{"%s"}, described
 below, as the first argument, and the string as the second, like this:
 
 @example
@@ -908,20 +914,30 @@ is shorter.
 Replace the specification with a single @samp{%}.  This format
 specification is unusual in that it does not use a value.  For example,
 @code{(format "%% %d" 30)} returns @code{"% 30"}.
+
+@item ‘
+@itemx ’
+@cindex curved quotes
+@cindex curly quotes
+Replace the specification with a left or right quote, respectively.
+Although typically a curved single quotation mark stands for itself,
+other quoting styles are available as per the variable
+@samp{text-quoting-style} described below.
 @end table
 
-  Any other format character results in an @samp{Invalid format
+  Any other format character after @samp{%} results in an @samp{Invalid format
 operation} error.
 
-  Here are several examples:
+  Here are several examples, which assume the typical quoting style
+where curved single quotes stand for themselves:
 
 @example
 @group
-(format "The name of this buffer is %s." (buffer-name))
-     @result{} "The name of this buffer is strings.texi."
+(format "The name of this buffer is ‘%s’." (buffer-name))
+     @result{} "The name of this buffer is ‘strings.texi’."
 
-(format "The buffer object prints as %s." (current-buffer))
-     @result{} "The buffer object prints as strings.texi."
+(format "The buffer object prints as ‘%s’." (current-buffer))
+     @result{} "The buffer object prints as ‘strings.texi’."
 
 (format "The octal value of %d is %o,
          and the hex value is %x." 18 18 18)
@@ -932,7 +948,7 @@ operation} error.
 
 @cindex field width
 @cindex padding
-  A specification can have a @dfn{width}, which is a decimal number
+  A @samp{%} specification can have a @dfn{width}, which is a decimal number
 between the @samp{%} and the specification character.  If the printed
 representation of the object contains fewer characters than this
 width, @code{format} extends it with padding.  The width specifier is
@@ -948,7 +964,7 @@ the width specifier normally consists of spaces inserted on the left:
 If the width is too small, @code{format} does not truncate the
 object's printed representation.  Thus, you can use a width to specify
 a minimum spacing between columns with no risk of losing information.
-In the following three examples, @samp{%7s} specifies a minimum width
+In the following two examples, @samp{%7s} specifies a minimum width
 of 7.  In the first case, the string inserted in place of @samp{%7s}
 has only 3 letters, and needs 4 blank spaces as padding.  In the
 second case, the string @code{"specification"} is 13 letters wide but
@@ -956,12 +972,12 @@ is not truncated.
 
 @example
 @group
-(format "The word '%7s' has %d letters in it."
+(format "The word ‘%7s’ has %d letters in it."
         "foo" (length "foo"))
-     @result{} "The word '    foo' has 3 letters in it."
-(format "The word '%7s' has %d letters in it."
+     @result{} "The word ‘    foo’ has 3 letters in it."
+(format "The word ‘%7s’ has %d letters in it."
         "specification" (length "specification"))
-     @result{} "The word 'specification' has 13 letters in it."
+     @result{} "The word ‘specification’ has 13 letters in it."
 @end group
 @end example
 
@@ -1003,14 +1019,14 @@ ignored.
 (format "%-6d is padded on the right" 123)
      @result{} "123    is padded on the right"
 
-(format "The word '%-7s' actually has %d letters in it."
+(format "The word ‘%-7s’ actually has %d letters in it."
         "foo" (length "foo"))
-     @result{} "The word 'foo    ' actually has 3 letters in it."
+     @result{} "The word ‘foo    ’ actually has 3 letters in it."
 @end group
 @end example
 
 @cindex precision in format specifications
-  All the specification characters allow an optional @dfn{precision}
+  The @samp{%} specification characters allow an optional @dfn{precision}
 before the character (after the width, if present).  The precision is
 a decimal-point @samp{.} followed by a digit-string.  For the
 floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the
@@ -1021,6 +1037,19 @@ shows only the first three characters of the representation for
 @var{object}.  Precision has no effect for other specification
 characters.
 
+@defvar text-quoting-style
+@cindex curved quotes
+@cindex curly quotes
+This variable specifies the style @code{format} uses when generating
+left and right quotes.  If the 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}, the style is @t{`like
+this'} with grave accent and apostrophe.  The default value @code{nil}
+acts like @code{curve} if curved single quotes are displayable, and
+like @code{grave} otherwise.
+@end defvar
+
 @node Case Conversion
 @section Case Conversion in Lisp
 @cindex upper case