Doc fixes for quoting

* doc/emacs/text.texi, doc/lispintro/emacs-lisp-intro.texi:
* doc/lispref/control.texi, doc/lispref/display.texi:
* doc/lispref/help.texi, doc/lispref/strings.texi, lisp/subr.el:
* src/callint.c, src/doprnt.c, src/editfns.c:
Document quoting a bit more systematically.
Problem reported by Alan Mackenzie (Bug#23425).

4 files changed, 24 insertions, 10 deletions

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 3f48c458c02..75d8d284623 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -1100,10 +1100,12 @@ These examples show typical uses of @code{error}:
 error symbol @code{error}, and a list containing the string returned by
 @code{format-message}.
 
-In a format string containing single quotes, curved quotes @t{‘like
-this’} and grave quotes @t{`like this'} work better than straight
-quotes @t{'like this'}, as @code{error} typically formats every
-straight quote as a curved closing quote.
+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.
 
 @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 c80f78c0e3b..b0cd8731fe2 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -265,10 +265,12 @@ properties, it is displayed with the specified faces (@pxref{Faces}).
 The string is also added to the @file{*Messages*} buffer, but without
 text properties (@pxref{Logging Messages}).
 
-In a format string containing single quotes, curved quotes @t{‘like
-this’} and grave quotes @t{`like this'} work better than straight
-quotes @t{'like this'}, as @code{message} typically formats every
-straight quote as a curved closing quote.
+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.
 
 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 58a11f29a4c..b945e438f55 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -335,10 +335,14 @@ specifies @var{mapvar}'s value as the keymap for any following
 @item ‘
 @itemx `
 (left single quotation mark and grave accent) both stand 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}.
 
 @item ’
 @itemx '
 (right single quotation mark and apostrophe) both stand for a right quote.
+This generates a right single quotation mark or an apostrophe
+depending on the value of @code{text-quoting-style}.
 
 @item \=
 quotes the following character and is discarded; thus, @samp{\=`} puts
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 9d6613c522c..c6563f7e03c 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -834,8 +834,14 @@ if any.
 This function acts like @code{format}, except it also converts any
 curved single quotes in @var{string} as per the value of
 @code{text-quoting-style}, and treats grave accent (@t{`}) and
-apostrophe (@t{'}) as if they were curved single quotes.  @xref{Keys
-in Documentation}.
+apostrophe (@t{'}) as if they were curved single quotes.
+
+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.
 @end defun
 
 @cindex @samp{%} in format