Improve the optional translation of quotes

Fix several problems with the recently-added custom variable
help-quote-translation where the code would quote inconsistently
in help buffers.  Add support for quoting 'like this', which
is common in other GNU programs in ASCII environments.  Change
help-quote-translation to use more mnemonic values: values are now the
initial quoting char, e.g., (setq help-quote-translation ?`) gets the
traditional Emacs help-buffer quoting style `like this'.  Change the
default behavior of substitute-command-keys to match what's done in
set-locale-environment, i.e., quote ‘like this’ if displayable,
'like this' otherwise.
* doc/lispref/help.texi (Keys in Documentation): Document
new behavior of substitute-command-keys, and document
help-quote-translation.
* doc/lispref/tips.texi (Documentation Tips):
Mention the effect of help-quote-translation.
* etc/NEWS: Mention new behavior of substitute-command-keys,
and merge help-quote-translation news into it.
When talking about doc strings, mention new ways to type quotes.
* lisp/cedet/mode-local.el (overload-docstring-extension):
Revert my recent change to this function, which shouldn't be
needed as the result is a doc string.
* lisp/cedet/mode-local.el (mode-local-print-binding)
(mode-local-describe-bindings-2):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode):
Use substitute-command-keys to ensure a more-consistent quoting
style in help buffers.
* lisp/cus-start.el (standard):
Document new help-quote-translation behavior.
* lisp/emacs-lisp/lisp-mode.el (lisp-fdefs):
* lisp/help-mode.el (help-xref-symbol-regexp, help-xref-info-regexp)
(help-xref-url-regexp):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Also match 'foo', in case we're in a help buffer generated when
help-quote-translation is ?'.
* src/doc.c: Include disptab.h, for DISP_CHAR_VECTOR.
(LEFT_SINGLE_QUOTATION_MARK, uLSQM0, uLSQM1, uLSQM2, uRSQM0)
(uRSQM1, uRSQM2, LSQM, RSQM): New constants.
(Fsubstitute_command_keys): Document and implement new behavior.
(Vhelp_quote_translation): Document new behavior.

1 files changed, 59 insertions, 30 deletions

diff --git a/src/doc.c b/src/doc.c
index 81b1354668f..2ea416f3a2b 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -32,6 +32,7 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
 #include "lisp.h"
 #include "character.h"
 #include "buffer.h"
+#include "disptab.h"
 #include "keyboard.h"
 #include "keymap.h"
 
@@ -683,6 +684,18 @@ the same file name is found in the `doc-directory'.  */)
   return unbind_to (count, Qnil);
 }
 
+/* Declare named constants for U+2018 LEFT SINGLE QUOTATION MARK and
+   U+2019 RIGHT SINGLE QUOTATION MARK, which have UTF-8 encodings
+   "\xE2\x80\x98" and "\xE2\x80\x99", respectively.  */
+enum
+  {
+    LEFT_SINGLE_QUOTATION_MARK = 0x2018,
+    uLSQM0 = 0xE2, uLSQM1 = 0x80, uLSQM2 = 0x98,
+    uRSQM0 = 0xE2, uRSQM1 = 0x80, uRSQM2 = 0x99,
+  };
+static unsigned char const LSQM[] = { uLSQM0, uLSQM1, uLSQM2 };
+static unsigned char const RSQM[] = { uRSQM0, uRSQM1, uRSQM2 };
+
 DEFUN ("substitute-command-keys", Fsubstitute_command_keys,
        Ssubstitute_command_keys, 1, 1, 0,
        doc: /* Substitute key descriptions for command names in STRING.
@@ -699,8 +712,10 @@ summary).
 Each substring of the form \\=\\<MAPVAR> specifies the use of MAPVAR
 as the keymap for future \\=\\[COMMAND] substrings.
 
-Each \\=` is replaced by ‘.  Each ' preceded by \\=` and without
-intervening ' is replaced by ’.
+Each \\=‘ and \\=’ are replaced by left and right quote.  Each \\=` is
+replaced by left quote, and each ' preceded by \\=` and without
+intervening ' is replaced by right quote.  Left and right quote
+characters are specified by ‘help-quote-translation’.
 
 \\=\\= quotes the following character and is discarded; thus,
 \\=\\=\\=\\= puts \\=\\= into the output, \\=\\=\\=\\[ puts \\=\\[ into the output, and
@@ -719,7 +734,7 @@ Otherwise, return a new string.  */)
   ptrdiff_t bsize;
   Lisp_Object tem;
   Lisp_Object keymap;
-  unsigned char *start;
+  unsigned char const *start;
   ptrdiff_t length, length_byte;
   Lisp_Object name;
   struct gcpro gcpro1, gcpro2, gcpro3, gcpro4;
@@ -735,6 +750,21 @@ Otherwise, return a new string.  */)
   name = Qnil;
   GCPRO4 (string, tem, keymap, name);
 
+  enum { unicode, grave_accent, apostrophe } quote_translation = unicode;
+  if (EQ (Vhelp_quote_translation, make_number ('`')))
+    quote_translation = grave_accent;
+  else if (EQ (Vhelp_quote_translation, make_number ('\'')))
+    quote_translation = apostrophe;
+  else if (NILP (Vhelp_quote_translation)
+           && DISP_TABLE_P (Vstandard_display_table))
+    {
+      Lisp_Object dv = DISP_CHAR_VECTOR (XCHAR_TABLE (Vstandard_display_table),
+                                         LEFT_SINGLE_QUOTATION_MARK);
+      if (VECTORP (dv) && ASIZE (dv) == 1
+          && EQ (AREF (dv, 0), make_number ('\'')))
+        quote_translation = apostrophe;
+    }
+
   multibyte = STRING_MULTIBYTE (string);
   nchars = 0;
 
@@ -932,38 +962,39 @@ Otherwise, return a new string.  */)
             strp = SDATA (string) + idx;
           }
         }
-      else if (EQ (Vhelp_quote_translation, Qprefer_unicode)
-               && (strp[0] == '`'))
+      else if (strp[0] == '`' && quote_translation == unicode)
         {
           in_quote = true;
-          start = (unsigned char *) "\xE2\x80\x98"; /* ‘ */
+          start = LSQM;
         subst_quote:
           length = 1;
           length_byte = 3;
           idx = strp - SDATA (string) + 1;
           goto subst;
         }
-      else if (EQ (Vhelp_quote_translation, Qprefer_unicode)
-               && (strp[0] == '\'' && in_quote))
+      else if (strp[0] == '`' && quote_translation == apostrophe)
+        {
+          *bufp++ = '\'';
+          strp++;
+          nchars++;
+          changed = true;
+        }
+      else if (strp[0] == '\'' && in_quote)
         {
           in_quote = false;
-          start = (unsigned char *) "\xE2\x80\x99"; /* ’ */
+          start = RSQM;
           goto subst_quote;
         }
-
-      else if (EQ (Vhelp_quote_translation, Qtraditional)
-               && (strp[0] == 0xE2)
-               && (strp[1] == 0x80)
-               && ((strp[2] == 0x98)      /* curly opening quote */
-                   || (strp[2] == 0x99))) /* curly closing quote */
+      else if (strp[0] == uLSQM0 && strp[1] == uLSQM1
+               && (strp[2] == uLSQM2 || strp[2] == uRSQM2)
+               && quote_translation != unicode)
         {
-          start = (strp[2] == 0x98) ? "`" : "'";
-          length = 1;
-          length_byte = 1;
-          idx = strp - SDATA (string) + 3;
-          goto subst;
+          *bufp++ = (strp[2] == uLSQM2 && quote_translation == grave_accent
+                     ? '`' : '\'');
+          strp += 3;
+          nchars++;
+          changed = true;
         }
-
       else if (! multibyte)             /* just copy other chars */
         *bufp++ = *strp++, nchars++;
       else
@@ -1005,15 +1036,13 @@ syms_of_doc (void)
   Vbuild_files = Qnil;
 
   DEFVAR_LISP ("help-quote-translation", Vhelp_quote_translation,
-               doc: /* How to translate quotes for display in *Help*.
-If the value is nil (default), no translation is done.
-If it's the symbol `traditional', any occurrences of the curly quotes
-are translated to their ASCII "equivalents", GRAVE and APOSTROPHE.
-If it's the symbol `prefer-unicode', any matched pairs of GRAVE and
-APOSTROPHE will get translated into the "equivalent" curly quotes.
-
-Note that any translation done is done in a fresh copy of the doc
-string, and doesn't overwrite the original characters. */);
+               doc: /* Style to use for single quotes in help.
+The value is a left single quote character of some style.
+Quote \\=‘like this\\=’ if the value is ?\\=‘ (left single quotation mark).
+Quote 'like this' if the value is ?' (apostrophe).
+Quote \\=`like this' if the value is ?\\=` (grave accent).
+The default value is nil, which means quote with left single quotation mark
+if displayable, and with apostrophe otherwise.  */);
   Vhelp_quote_translation = Qnil;
 
   defsubr (&Sdocumentation);