Re: how to turn off automatic curly-quoting?

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

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

Drew Adams wrote:

> Does it restore the behavior as it was - everywhere?

Yes and no.  It does restore behavior for doc strings in traditional format that 
uses grave accent and apostrophe to quote.  However, it does transliterate 
curved quotes in doc strings to grave accent and apostrophe, which is new. 
Presumably any such doc strings are recent introductions so this caveat 
shouldn't affect traditional usage.

> This feature should be opt-in, not opt-out, IMHO.

No, let's enable it in environments where it seems to work.  That's what other 
GNU projects do (GCC, coreutils, etc.).  The new feature is disabled by default 
in traditional environments that can't display curved quotes; that should be 
good enough.

> Please consider also changing the option values so that
> you can use `M-x set-variable` in a reasonable way (i.e.,
> without needing to know that ?` is 96 etc. - you cannot
> type ?` at the prompt).  Character values are not helpful
> in such a context.

Alan made a similar suggestion a while ago, and it's easy enough to implement. 
Done in the attached patch, which I pushed just now.

> Also, why is the name about "translation"?  Shouldn't
> this option just be about what style is used for quoting
> Emacs terms?

That point has also been made.  I changed the name to 'text-quoting-style' in 
the attached patch.  Although it's just a name, it does have uses outside help 
buffers so at least the 'help' part of the name was misleading.  Other Emacs 
packages (e.g., coreutils) use "quoting-style" but that's too generic for Emacs 
which has other interpretation of the word "quoting".

> FWIW: The doc string of `substitute-command-keys' is
> not too bad.  But I find it confusing that it refers
> to "left and right quote characters" as something other
> than the "quotation mark" character referred to in the
> doc of `help-quote-translation'.

I don't see the confusion, quite possibly because I'm too close to the code. 
Suggestions for improved wording would be welcome.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Redo-text-quoting-style-variable.patch --]
[-- Type: text/x-diff; name="0001-Redo-text-quoting-style-variable.patch", Size: 8925 bytes --]

From 416d7fd2d863935b7ef4ed349f6c72f14e73dd4d Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sun, 2 Aug 2015 15:58:02 -0700
Subject: [PATCH] Redo text-quoting-style variable

Rename help-quote-translation to text-quoting-style,
and use symbols rather than characters as values.
This follows suggestions along these lines by Alan Mackenzie in:
http://lists.gnu.org/archive/html/emacs-devel/2015-06/msg00343.html
and by Drew Adams in:
http://lists.gnu.org/archive/html/emacs-devel/2015-08/msg00048.html
* doc/lispref/help.texi (Keys in Documentation)
* etc/NEWS:
* lisp/cus-start.el (standard):
* src/doc.c (Fsubstitute_command_keys, syms_of_doc):
Document and/or implement the new behavior instead of the old.
(syms_of_doc): New symbols 'grave' and 'straight'.
---
 doc/lispref/help.texi | 16 ++++++++--------
 etc/NEWS              | 20 ++++++++++----------
 lisp/cus-start.el     | 18 ++++++++++--------
 src/doc.c             | 27 ++++++++++++++-------------
 4 files changed, 42 insertions(+), 39 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 779a0d5..ca8ae3f 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -347,18 +347,18 @@ and @samp{\=\=} puts @samp{\=} into the output.
 @strong{Please note:} Each @samp{\} must be doubled when written in a
 string in Emacs Lisp.
 
-@defvar help-quote-translation
+@defvar text-quoting-style
 @cindex curved quotes
 @cindex curly quotes
 The value of this variable specifies the style
 @code{substitute-command-keys} uses when generating left and right
-quotes.  If the variable's value is @code{?‘} (U+2018 LEFT SINGLE
-QUOTATION MARK), the style is @t{‘like this’} with curved single
-quotes.  If the value is @code{?'} (apostrophe), the style is @t{'like
-this'} with apostrophes.  If the value is @code{?`} (grave accent),
-the style is @t{`like this'} with grave accent and apostrophe.  The
-default value @code{nil} means to use curved single quotes if
-displayable, and grave accent and apostrophe otherwise.
+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
 
 @defun substitute-command-keys string
diff --git a/etc/NEWS b/etc/NEWS
index 85df716..e384d17 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -889,14 +889,14 @@ in languages like German where downcasing rules depend on grammar.
 +++
 ** substitute-command-keys now replaces quotes.
 That is, it converts documentation strings' quoting style as per the
-value of the new custom variable ‘help-quote-translation’: ?‘ means
-use curved quotes (also known as curly quotes) ‘like this’, ?' means
-use apostrophes 'like this', ?` means use grave accent and apostrophe
-`like this', and nil (default) means use curved quotes if displayable
-and grave accent and apostrophe otherwise.  Doc strings in source code
-can use either curved quotes or grave accent and apostrophe.  As
-before, isolated apostrophes and characters preceded by \= are output
-as-is.
+value of the new custom variable ‘text-quoting-style’: ‘curve’ means
+use curved quotes (also known as curly quotes) ‘like this’, ‘straight’
+means use straight apostrophes 'like this', ‘grave’ means use grave
+accent and apostrophe `like this', and nil (default) means use curved
+quotes if displayable and grave accent and apostrophe otherwise.  Doc
+strings in source code can use either curved quotes or grave accent
+and apostrophe.  As before, isolated apostrophes and characters
+preceded by \= are output as-is.
 
 +++
 ** The character classes [:alpha:] and [:alnum:] in regular expressions
@@ -1017,8 +1017,8 @@ In the new Electric Quote mode, you can enter curved single quotes
 into documentation by typing ` and '.  Outside Electric Quote mode,
 you can enter them by typing ‘C-x 8 [’ and ‘C-x 8 ]’, or (if your Alt
 key works) by typing ‘A-[’ and ‘A-]’.  As described above under
-‘help-quote-translation’, the user can specify how to display doc
-string quotes.
+‘text-quoting-style’, the user can specify how to display doc string
+quotes.
 
 +++
 ** show-help-function's arg is converted via substitute-command-keys
diff --git a/lisp/cus-start.el b/lisp/cus-start.el
index 69dbf0d..7a37198 100644
--- a/lisp/cus-start.el
+++ b/lisp/cus-start.el
@@ -221,14 +221,16 @@ Leaving \"Default\" unchecked is equivalent with specifying a default of
 	     (no-redraw-on-reenter display boolean)
 
 	     ;; doc.c
-	     (help-quote-translation help
-				     (choice
-				      (character :tag "Quote with curved quotes"
-                                                 :value ?‘)
-				      (character :tag "Quote 'like this'" :value ?\')
-				      (character :tag "Quote `like this'" :value ?\`)
-				      (const :tag "Quote with curved quotes if displayable, 'like this' otherwise" nil))
-				     "25.1")
+	     (text-quoting-style
+              help
+              (choice
+               (const :tag "Quote with curved single quotes" curve)
+               (const :tag "Quote with straight apostrophes 'like this'"
+                      straight)
+               (const :tag "Quote with grave accent and apostrophe `like this'"
+                      grave)
+               (const :tag "Use curved quotes if displayable, grave accent and apostrophe otherwise" nil))
+              "25.1")
              ;; dosfns.c
 	     (dos-display-scancodes display boolean)
 	     (dos-hyper-key keyboard integer)
diff --git a/src/doc.c b/src/doc.c
index 78a7815..36619e1 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -715,7 +715,7 @@ as the keymap for future \\=\\[COMMAND] substrings.
 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’.
+characters are specified by ‘text-quoting-style’.
 
 \\=\\= quotes the following character and is discarded; thus,
 \\=\\=\\=\\= puts \\=\\= into the output, \\=\\=\\=\\[ puts \\=\\[ into the output, and
@@ -751,11 +751,11 @@ Otherwise, return a new string.  */)
   GCPRO4 (string, tem, keymap, name);
 
   enum { unicode, grave_accent, apostrophe } quote_translation = unicode;
-  if (EQ (Vhelp_quote_translation, make_number ('`')))
+  if (EQ (Vtext_quoting_style, Qgrave))
     quote_translation = grave_accent;
-  else if (EQ (Vhelp_quote_translation, make_number ('\'')))
+  else if (EQ (Vtext_quoting_style, Qstraight))
     quote_translation = apostrophe;
-  else if (NILP (Vhelp_quote_translation)
+  else if (NILP (Vtext_quoting_style)
 	   && DISP_TABLE_P (Vstandard_display_table))
     {
       Lisp_Object dv = DISP_CHAR_VECTOR (XCHAR_TABLE (Vstandard_display_table),
@@ -1024,6 +1024,8 @@ void
 syms_of_doc (void)
 {
   DEFSYM (Qfunction_documentation, "function-documentation");
+  DEFSYM (Qgrave, "grave");
+  DEFSYM (Qstraight, "straight");
 
   DEFVAR_LISP ("internal-doc-file-name", Vdoc_file_name,
 	       doc: /* Name of file containing documentation strings of built-in symbols.  */);
@@ -1033,15 +1035,14 @@ syms_of_doc (void)
                doc: /* A list of files used to build this Emacs binary.  */);
   Vbuild_files = Qnil;
 
-  DEFVAR_LISP ("help-quote-translation", Vhelp_quote_translation,
-               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 grave accent otherwise.  */);
-  Vhelp_quote_translation = Qnil;
+  DEFVAR_LISP ("text-quoting-style", Vtext_quoting_style,
+               doc: /* Style to use for single quotes when generating text.
+‘curve’ means quote with curved single quotes \\=‘like this\\=’.
+‘straight’ means quote with straight apostrophes 'like this'.
+‘grave’ means quote with grave accent and apostrophe \\=`like this'.
+The default value nil acts like ‘curve’ if curved single quotes are
+displayable, and like ‘grave’ otherwise.  */);
+  Vtext_quoting_style = Qnil;
 
   defsubr (&Sdocumentation);
   defsubr (&Sdocumentation_property);
-- 
2.1.0