bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> Emacs's traditional doc string style has been to quote symbols
> `like this'.  This worked well on older terminals where ` and '
> were symmetric quotes,

And it has worked well in GUI Emacs as well.  And it still does.
And it supports simple highlighting, and simple searching, which
are very helpful to users.

This notation is not just some primitive, prehistoric way of setting
off symbols and other code.  It is a thoroughly modern way of doing
that.  Especially for a context that is plain text and that involves
simple (and complex) editing operations.

> but nowadays this quoting looks odd 

No, it doesn't.  It doesn't look more odd than it did pre-"nowadays".

> and it's better to use apostrophe for single-quoted ASCII text.

"It's better"?  That's all you can say in support of this change?
No reason given?

Or was your "nowdays this quoting looks odd" to you the reason?
If so, that's a feeble reason to lose helpful and simple
highlighting, and to change a longstanding convention.

> Add support for quoting either way, suggesting the newer style.
> ... Quote symbols 'like-this' as well as `like-this'.
> Recommend the former style.

Please don't.  Don't even add support for '...' quoting.  It will
just get in the way.  Of users.  Of tools.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > > Info files in the Emacs distribution already use curved single
> > > quotes.
> >
> > I sure hope not.  That's not the case in the Windows binary builds
> > I was able to download.  But there is no Windows build for the
> > latest release.  That will certainly be a step backward, if what
> > you say is true.
> 
> This depends on the version of Texinfo used to generate the Info
> files.  With the latest version, what Paul says is true.

Yes, but I thought you were keeping an eye out, Eli ;-), and making
sure that at least the Windows Emacs builds used an older version.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 13:15:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: eggert@cs.ucla.edu, nicolas@petton.fr, 20385@debbugs.gnu.org
> 
> > > > Info files in the Emacs distribution already use curved single
> > > > quotes.
> > >
> > > I sure hope not.  That's not the case in the Windows binary builds
> > > I was able to download.  But there is no Windows build for the
> > > latest release.  That will certainly be a step backward, if what
> > > you say is true.
> > 
> > This depends on the version of Texinfo used to generate the Info
> > files.  With the latest version, what Paul says is true.
> 
> Yes, but I thought you were keeping an eye out, Eli ;-), and making
> sure that at least the Windows Emacs builds used an older version.

I have no such power on work done by others.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > > Those who follow Markus Kuhn's advice, read here:
> > >   http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html
> >
> > ...where the *only* argument given is, again, "it looked rather
> > ugly".  That is the only "why do they want that" that we have
> > heard, so far.
> 
> You are missing the point: this paper wants those "rather ugly"
> characters to disappear from text content, and not everybody out
> there uses Emacs for editing and reading that.

No, I didn't miss the fact that the paper is not about Emacs etc.
The only _reason given_ in that paper for dropping use of `...'
quoting (anywhere, everywhere) is what I quoted: "it looked rather
ugly".

> So an Emacs-only solution that just _shows_ the nice characters,
> leaving the underlying text with `..' is not what that paper
> wants, or preaches for.

Agreed, but that has nothing to do with what I said.  He goes
beyond wanting nice appearance, yes.  He wants the content to
reflect the appearance, yes.  But the only reason he gave for
any change was the "rather ugly" appearance.

> > And of course Mr. Kuhn is not specifically talking about an
> > environment such as Emacs, where you do more with text than
> > just read it.
> 
> He doesn't talk about Emacs at all.

You are repeating my point.  He is not talking about Emacs or
anything similar to Emacs.  Except that he seems to be talking
generally: As you say, "the old quoting characters" should
"never be used" anywhere "for quoting purposes".

That includes Emacs.  But he does not speak to the uses of
`...' in a context like Emacs.  He wants all contexts to change,
but he makes no argument that takes a context like Emacs into
account.

> He's talking about the world at large.  People who want to
> follow him want the old quoting characters to never be used
> at all for quoting purposes.

Maybe so.  But the argument given is far too weak to apply to
Emacs.  That "rather ugly" reason might be sufficient for some
people for some contexts.  It is not a strong argument for a
context like Emacs.

In the context of Emacs we should hear something more in favor
of such a change.  So far, we haven't.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Fri, 24 Apr 2015 07:11:24 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dgutov@yandex.ru, 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> 
> > > > Those who follow Markus Kuhn's advice, read here:
> > > >   http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html
> > >
> > > ...where the *only* argument given is, again, "it looked rather
> > > ugly".  That is the only "why do they want that" that we have
> > > heard, so far.
> > 
> > You are missing the point: this paper wants those "rather ugly"
> > characters to disappear from text content, and not everybody out
> > there uses Emacs for editing and reading that.
> 
> No, I didn't miss the fact that the paper is not about Emacs etc.
> The only _reason given_ in that paper for dropping use of `...'
> quoting (anywhere, everywhere) is what I quoted: "it looked rather
> ugly".

What other reasons can there be for replacing one character with
another?

> > He doesn't talk about Emacs at all.
> 
> You are repeating my point.  He is not talking about Emacs or
> anything similar to Emacs.  Except that he seems to be talking
> generally: As you say, "the old quoting characters" should
> "never be used" anywhere "for quoting purposes".
> 
> That includes Emacs.  But he does not speak to the uses of
> `...' in a context like Emacs.  He wants all contexts to change,
> but he makes no argument that takes a context like Emacs into
> account.

He doesn't care.  Read his other articles, and you will see.

> > He's talking about the world at large.  People who want to
> > follow him want the old quoting characters to never be used
> > at all for quoting purposes.
> 
> Maybe so.  But the argument given is far too weak to apply to
> Emacs.  That "rather ugly" reason might be sufficient for some
> people for some contexts.  It is not a strong argument for a
> context like Emacs.

For you, but you are biased.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Emacs's traditional doc string style has been to quote symbols
`like this'.  This worked well on older terminals where ` and '
were symmetric quotes, but nowadays this quoting looks odd and
it's better to use apostrophe for single-quoted ASCII text.
Add support for quoting either way, suggesting the newer style.
* doc/lispref/tips.texi (Documentation Tips): Quote symbols
'like-this' as well as `like-this'.  Recommend the former style.
* etc/NEWS: Mention this.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* 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):
Parse symbols quoted 'like-this' as well as `like-this'.
---
 doc/lispref/tips.texi           | 27 ++++++++++++++++-----------
 etc/NEWS                        |  4 ++++
 lisp/cedet/srecode/texi.el      |  2 +-
 lisp/emacs-lisp/checkdoc.el     |  4 ++--
 lisp/emacs-lisp/lisp-mode.el    |  8 ++++----
 lisp/finder.el                  |  2 +-
 lisp/gnus/gnus-art.el           |  8 ++++----
 lisp/help-mode.el               |  6 +++---
 lisp/international/mule-cmds.el |  2 +-
 lisp/wid-edit.el                |  2 +-
 10 files changed, 37 insertions(+), 28 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..8997249 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -658,17 +658,22 @@ starting double-quote is not part of the string!
 @anchor{Docstring hyperlinks}
 @item
 When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with a grave
-accent @samp{`} before and apostrophe @samp{'} after it.  There are
+would be printed (which usually means in lower case), with a
+apostrophe @samp{'} before and after it.  There are
 two exceptions: write @code{t} and @code{nil} without surrounding
-punctuation.  For example: @samp{CODE can be `lambda', nil, or t.}
+punctuation.  For example: @samp{CODE can be 'lambda', nil, or t.}
 (In this manual, we use a different convention, with single-quotes
 around symbols.)
 
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @samp{`} and apostrophe, rather
+than with two apostrophes: @samp{`like-this'} rather than
+@samp{'like-this'}.  This older single-quoting convention is not
+recommended for new documentation.
+
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name between grave accent and apostrophe, if the symbol
-has either a
+uses a single-quoted symbol name, if the symbol has either a
 function or a variable definition.  You do not need to do anything
 special to make use of this feature.  However, when a symbol has both a
 function definition and a variable definition, and you want to refer to
@@ -710,21 +715,21 @@ followed by the word @samp{face}.  In that case, only the face
 documentation will be shown, even if the symbol is also defined as a
 variable or as a function.
 
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) between grave accent and apostrophe, preceded by
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
 @samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
 anchor}.  The Info file name defaults to @samp{emacs}.  For example,
 
 @smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+See Info node 'Font Lock' and Info node '(elisp)Font Lock Basics'.
 @end smallexample
 
-Finally, to create a hyperlink to URLs, write the URL between grave
-accent and apostrophe, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}. For example,
 
 @smallexample
 The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
+'http://www.gnu.org/').
 @end smallexample
 
 @item
diff --git a/etc/NEWS b/etc/NEWS
index a9c0d2e..278754e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -791,6 +791,10 @@ name.  The variable `system-name' is now obsolete.
 *** New macros `thread-first' and `thread-last' allow threading a form
     as the first or last argument of subsequent forms.
 
+** Documentation strings now support single-quoting 'like-this'
+in addition to the older style `like-this'.  The newer style looks
+better on most modern displays, and is recommended for new code.
+
 +++
 ** Time-related changes:
 
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index 5c3f21c..d03203d 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -253,7 +253,7 @@ that class.
  [ stuff ]  => @code{[ stuff ]}
  Key        => @kbd{Key}     (key is C\\-h, M\\-h, SPC, RET, TAB and the like)
  ...        => @dots{}"
-  (while (string-match "`\\([-a-zA-Z0-9<>.]+\\)'" string)
+  (while (string-match "['`]\\([-a-zA-Z0-9<>.]+\\)'" string)
     (let* ((vs (substring string (match-beginning 1) (match-end 1)))
 	   (v (intern-soft vs)))
       (setq string
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 777fed0..d861da9 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1554,7 +1554,7 @@ mouse-[0-3]\\)\\)\\>"))
      (save-excursion
        (let ((case-fold-search t)
 	     (ret nil) mb me)
-	 (while (and (re-search-forward "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
+	 (while (and (re-search-forward "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
 		     (not ret))
 	   (let* ((ms1 (match-string 1))
 		  (sym (intern-soft ms1)))
@@ -1824,7 +1824,7 @@ Replace with \"%s\"? " original replace)
 	   nil)))
      ;; t and nil case
      (save-excursion
-       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
+       (if (re-search-forward "\\(['`]\\(t\\|nil\\)'\\)" e t)
 	   (if (checkdoc-autofix-ask-replace
 		(match-beginning 1) (match-end 1)
 		(format "%s should not appear in quotes.  Remove? "
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 26a21d5..bfdd41e 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -405,8 +405,8 @@
        ;; Words inside \\[] tend to be for `substitute-command-keys'.
        ("\\\\\\\\\\[\\(\\(?:\\sw\\|\\s_\\)+\\)\\]"
         (1 font-lock-constant-face prepend))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside '' and `' tend to be symbol names.
+       ("['`]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
@@ -454,8 +454,8 @@
        ;; Erroneous structures.
        (,(concat "(" cl-errs-re "\\_>")
         (1 font-lock-warning-face))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside '' and `' tend to be symbol names.
+       ("['`]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
diff --git a/lisp/finder.el b/lisp/finder.el
index 47fab3c..847dccc 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -115,7 +115,7 @@ Each element has the form (KEYWORD . DESCRIPTION).")
   "Syntax table used while in `finder-mode'.")
 
 (defvar finder-font-lock-keywords
-  '(("`\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
+  '(("['`]\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
   "Font-lock keywords for Finder mode.")
 
 (defvar finder-headmark nil
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 14f9adc..4560a0e 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -7828,11 +7828,11 @@ positives are possible."
     ("/\\([a-z][-a-z0-9]+\\.el\\)\\>[^.?]"
      ;; Exclude [.?] for URLs in gmane.emacs.cvs
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][-a-z0-9]+\\.el\\)'"
+    ("['`]\\([a-z][-a-z0-9]+\\.el\\)'"
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
+    ("['`]\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
      0 (>= gnus-button-emacs-level 8) gnus-button-handle-symbol 1)
-    ("`\\([a-z][a-z0-9]+-[a-z]+\\)'"
+    ("['`]\\([a-z][a-z0-9]+-[a-z]+\\)'"
      0 (>= gnus-button-emacs-level 9) gnus-button-handle-symbol 1)
     ("(setq[ \t\n]+\\([a-z][a-z0-9]+-[-a-z0-9]+\\)[ \t\n]+.+)"
      1 (>= gnus-button-emacs-level 7) gnus-button-handle-describe-variable 1)
@@ -7842,7 +7842,7 @@ positives are possible."
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-function 2)
     ("\\b\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>"
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2)
-    ("`\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
+    ("['`]\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
      ;; Unlike the other regexps we really have to require quoting
      ;; here to determine where it ends.
      1 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-key 3)
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d6679e9..13e5ed4 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -322,7 +322,7 @@ Commands:
 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
 		    "[ \t\n]+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+		    "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
   "Regexp matching doc string references to symbols.
 
 The words preceding the quoted symbol can be used in doc strings to
@@ -337,11 +337,11 @@ when help commands related to multilingual environment (e.g.,
 
 
 (defconst help-xref-info-regexp
-  (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+  (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+['`]\\([^']+\\)'")
   "Regexp matching doc string references to an Info node.")
 
 (defconst help-xref-url-regexp
-  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+['`]\\([^']+\\)'")
   "Regexp matching doc string references to a URL.")
 
 ;;;###autoload
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index cca659f..0856995 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -177,7 +177,7 @@
 		    "\\(charset\\)"
 		    "\\)\\s-+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
+		    "['`]\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
 
 (defun coding-system-change-eol-conversion (coding-system eol-type)
   "Return a coding system which differs from CODING-SYSTEM in EOL conversion.
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 04a900f..9e1c895 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2855,7 +2855,7 @@ The following properties have special meanings for this widget:
   :type 'boolean
   :group 'widget-documentation)
 
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "['`]\\([^\n`' ]+\\)'"
   "Regexp for matching potential links in documentation strings.
 The first group should be the link itself."
   :type 'regexp
-- 
2.1.0

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

> Emacs's traditional doc string style has been to quote symbols
> `like this'.  This worked well on older terminals where ` and '
> were symmetric quotes, but nowadays this quoting looks odd and
> it's better to use apostrophe for single-quoted ASCII text.
> Add support for quoting either way, suggesting the newer style.

I'm not sure I like this.  Yet, I don't like the look for `...' either.


        Stefan

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

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

On 04/20/2015 12:37 PM, Stefan Monnier wrote:
> I don't like the look for `...' either.

Yes, it's a problem.

For better looks we can use curved single quotes, e.g., instead of the current:

   Indent each line via `indent-according-to-mode'.

we can use:

   Indent each line via ‘indent-according-to-mode’.

Curved single quotes nest better than apostrophe pairs, look better than grave 
accent + apostrophe, and avoid the "misuse" of grave accent for quoting.  A 
revised patch is attached.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Support-quoting-like-this-in-doc-strings.patch --]
[-- Type: text/x-patch; name="0001-Support-quoting-like-this-in-doc-strings.patch", Size: 13214 bytes --]

From 50230afd8ec29a6c26b55920accc2e2b50f9b518 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 20 Apr 2015 17:12:58 -0700
Subject: [PROPOSED PATCH] =?UTF-8?q?Support=20quoting=20=E2=80=98like=20th?=
 =?UTF-8?q?is'=20in=20doc=20strings?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Emacs's traditional doc string style has been to quote symbols
`like this'.  This worked well on older terminals where ` and '
were symmetric quotes, but nowadays this quoting looks odd and
it's better to use curved single quotes for text.
Add support for quoting either way, suggesting the newer style.
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.  Recommend the former style.
* etc/NEWS: Mention this.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* 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):
Parse symbols quoted ‘like-this’ as well as `like-this'.
---
 doc/lispref/tips.texi           | 34 +++++++++++++++++++---------------
 etc/NEWS                        |  5 +++++
 lisp/cedet/srecode/texi.el      |  2 +-
 lisp/emacs-lisp/checkdoc.el     |  5 +++--
 lisp/emacs-lisp/lisp-mode.el    |  8 ++++----
 lisp/finder.el                  |  2 +-
 lisp/gnus/gnus-art.el           |  8 ++++----
 lisp/help-mode.el               |  7 ++++---
 lisp/international/mule-cmds.el |  2 +-
 lisp/wid-edit.el                |  2 +-
 10 files changed, 43 insertions(+), 32 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..bfcf914 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -658,17 +658,21 @@ starting double-quote is not part of the string!
 @anchor{Docstring hyperlinks}
 @item
 When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with a grave
-accent @samp{`} before and apostrophe @samp{'} after it.  There are
+would be printed (which usually means in lower case), with surrounding
+it with curved single quotes (@samp{‘} U+2018 LEFT SINGLE QUOTATION
+MARK and @samp{’} U+2019 right single quotation mark).  There are
 two exceptions: write @code{t} and @code{nil} without surrounding
-punctuation.  For example: @samp{CODE can be `lambda', nil, or t.}
-(In this manual, we use a different convention, with single-quotes
-around symbols.)
+punctuation.  For example: @samp{CODE can be ‘lambda’, nil, or t.}
+
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @samp{`} and apostrophe
+@samp{'}: @samp{`like-this'} rather than @samp{‘like-this’}.  As the
+older convention looks odd on modern displays, it is not recommended
+for new documentation.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name between grave accent and apostrophe, if the symbol
-has either a
+uses a single-quoted symbol name, if the symbol has either a
 function or a variable definition.  You do not need to do anything
 special to make use of this feature.  However, when a symbol has both a
 function definition and a variable definition, and you want to refer to
@@ -678,7 +682,7 @@ immediately before the symbol name.  (Case makes no difference in
 recognizing these indicator words.)  For example, if you write
 
 @example
-This function sets the variable `buffer-file-name'.
+This function sets the variable ‘buffer-file-name’.
 @end example
 
 @noindent
@@ -691,7 +695,7 @@ you can write the words @samp{symbol} or @samp{program} before the
 symbol name to prevent making any hyperlink.  For example,
 
 @example
-If the argument KIND-OF-RESULT is the symbol `list',
+If the argument KIND-OF-RESULT is the symbol ‘list’,
 this function returns a list of all the objects
 that satisfy the criterion.
 @end example
@@ -710,21 +714,21 @@ followed by the word @samp{face}.  In that case, only the face
 documentation will be shown, even if the symbol is also defined as a
 variable or as a function.
 
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) between grave accent and apostrophe, preceded by
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
 @samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
 anchor}.  The Info file name defaults to @samp{emacs}.  For example,
 
 @smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+See Info node ‘Font Lock’ and Info node ‘(elisp)Font Lock Basics’.
 @end smallexample
 
-Finally, to create a hyperlink to URLs, write the URL between grave
-accent and apostrophe, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}.  For example,
 
 @smallexample
 The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
+‘http://www.gnu.org/’).
 @end smallexample
 
 @item
diff --git a/etc/NEWS b/etc/NEWS
index 9dd0e15..9a31147 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -796,6 +796,11 @@ name.  The variable `system-name' is now obsolete.
 *** New macros `thread-first' and `thread-last' allow threading a form
     as the first or last argument of subsequent forms.
 
+** Documentation strings now support quoting with curved single quotes
+‘like-this’ in addition to the older style with grave accent and
+apostrophe `like-this'.  The newer style looks better on most modern
+displays, and is recommended for new code.
+
 +++
 ** Time-related changes:
 
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index 5c3f21c..5068b2a 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -253,7 +253,7 @@ that class.
  [ stuff ]  => @code{[ stuff ]}
  Key        => @kbd{Key}     (key is C\\-h, M\\-h, SPC, RET, TAB and the like)
  ...        => @dots{}"
-  (while (string-match "`\\([-a-zA-Z0-9<>.]+\\)'" string)
+  (while (string-match "[`‘]\\([-a-zA-Z0-9<>.]+\\)['’]" string)
     (let* ((vs (substring string (match-beginning 1) (match-end 1)))
 	   (v (intern-soft vs)))
       (setq string
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 777fed0..d6a4c7b 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1554,7 +1554,8 @@ mouse-[0-3]\\)\\)\\>"))
      (save-excursion
        (let ((case-fold-search t)
 	     (ret nil) mb me)
-	 (while (and (re-search-forward "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
+	 (while (and (re-search-forward
+                      "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]" e t)
 		     (not ret))
 	   (let* ((ms1 (match-string 1))
 		  (sym (intern-soft ms1)))
@@ -1824,7 +1825,7 @@ Replace with \"%s\"? " original replace)
 	   nil)))
      ;; t and nil case
      (save-excursion
-       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
+       (if (re-search-forward "\\([`‘]\\(t\\|nil\\)['’]\\)" e t)
 	   (if (checkdoc-autofix-ask-replace
 		(match-beginning 1) (match-end 1)
 		(format "%s should not appear in quotes.  Remove? "
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 26a21d5..2c8bbee 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -405,8 +405,8 @@
        ;; Words inside \\[] tend to be for `substitute-command-keys'.
        ("\\\\\\\\\\[\\(\\(?:\\sw\\|\\s_\\)+\\)\\]"
         (1 font-lock-constant-face prepend))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside ‘’ and `' tend to be symbol names.
+       ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
@@ -454,8 +454,8 @@
        ;; Erroneous structures.
        (,(concat "(" cl-errs-re "\\_>")
         (1 font-lock-warning-face))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside ‘’ and `' tend to be symbol names.
+       ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
diff --git a/lisp/finder.el b/lisp/finder.el
index 47fab3c..306f2e2 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -115,7 +115,7 @@ Each element has the form (KEYWORD . DESCRIPTION).")
   "Syntax table used while in `finder-mode'.")
 
 (defvar finder-font-lock-keywords
-  '(("`\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
+  '(("[`‘]\\([^'`‘’]+\\)['’]" 1 font-lock-constant-face prepend))
   "Font-lock keywords for Finder mode.")
 
 (defvar finder-headmark nil
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 14f9adc..ac3819d 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -7828,11 +7828,11 @@ positives are possible."
     ("/\\([a-z][-a-z0-9]+\\.el\\)\\>[^.?]"
      ;; Exclude [.?] for URLs in gmane.emacs.cvs
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][-a-z0-9]+\\.el\\)'"
+    ("[`‘]\\([a-z][-a-z0-9]+\\.el\\)['’]"
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 8) gnus-button-handle-symbol 1)
-    ("`\\([a-z][a-z0-9]+-[a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 9) gnus-button-handle-symbol 1)
     ("(setq[ \t\n]+\\([a-z][a-z0-9]+-[-a-z0-9]+\\)[ \t\n]+.+)"
      1 (>= gnus-button-emacs-level 7) gnus-button-handle-describe-variable 1)
@@ -7842,7 +7842,7 @@ positives are possible."
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-function 2)
     ("\\b\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>"
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2)
-    ("`\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
+    ("[`‘]\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^'’]+\\)\\)['’]"
      ;; Unlike the other regexps we really have to require quoting
      ;; here to determine where it ends.
      1 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-key 3)
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d6679e9..cf8ec0c 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -322,7 +322,7 @@ Commands:
 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
 		    "[ \t\n]+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]"))
   "Regexp matching doc string references to symbols.
 
 The words preceding the quoted symbol can be used in doc strings to
@@ -337,11 +337,12 @@ when help commands related to multilingual environment (e.g.,
 
 
 (defconst help-xref-info-regexp
-  (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+  (purecopy
+   "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to an Info node.")
 
 (defconst help-xref-url-regexp
-  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to a URL.")
 
 ;;;###autoload
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index cca659f..ae0abec 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -177,7 +177,7 @@
 		    "\\(charset\\)"
 		    "\\)\\s-+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]")))
 
 (defun coding-system-change-eol-conversion (coding-system eol-type)
   "Return a coding system which differs from CODING-SYSTEM in EOL conversion.
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 04a900f..7a34c1f 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2855,7 +2855,7 @@ The following properties have special meanings for this widget:
   :type 'boolean
   :group 'widget-documentation)
 
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "[`‘]\\([^\n `'‘’]+\\)['’]"
   "Regexp for matching potential links in documentation strings.
 The first group should be the link itself."
   :type 'regexp
-- 
2.1.0

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> For better looks we can use curved single quotes, e.g., instead of the
> current:
>    Indent each line via `indent-according-to-mode'.
> we can use:
>    Indent each line via ‘indent-according-to-mode’.
> 
> Curved single quotes nest better than apostrophe pairs, look better than
> grave accent + apostrophe, and avoid the "misuse" of grave accent for
> quoting.  A revised patch is attached.

Again, please don't.  It is much simpler to search for ` and ', which
are available directly from most keyboards, than it is to search for
‘ and ’.

Please find something else you are interested in, to improve. ;-)
There are plenty of thing to work on, to improve Emacs.  Tons of
bugs reported, to start with...

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

>   Indent each line via ‘indent-according-to-mode’.

Yes, I like the way it looks and the way it's even less ambiguous than
`...'.  So I think it's the *right* solution.
But I've resisted going this way so far because of the difficulty to
type those things.
IOW, I think we need some clever way to type them in with very little effort.


        Stefan

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> >   Indent each line via ‘indent-according-to-mode’.
> 
> Yes, I like the way it looks and the way it's even less ambiguous than
> `...'.  So I think it's the *right* solution.   But I've resisted going
> this way so far because of the difficulty to type those things.  IOW,
> I think we need some clever way to type them in with very little effort.

Typing them is one problem, for sure.  Then there is the problem
of using them in Lisp (and other programming language) code.

Will Emacs Lisp start using ‘ the same way it uses `, and ’ the same
way it uses '?  If not, then some of the ` marks in the manual will
change to ‘ and some not, etc.  It's doable, but you would do well
to imagine the repercussions for users before going down that road.

And that's only once you've solved the "clever way to type them"
question.

I'd suggest not worrying about this problem now - it will be there
when you're done fixing other things. ;-)  Things like making it
possible in Isearch to handle certain groups of chars (‘ and `,
for instance) as equivalence classes.  That is a harder nut to
crack, but also one that is genuinely worthwhile cracking.

(And no, that is not related to `...' -> ‘...’.  Just mentioning
it as something more important to fix, with a bigger payoff.)

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

> Will Emacs Lisp start using ‘ the same way it uses `, and ’ the same
> way it uses '?

Of course not.

> I'd suggest not worrying about this problem now - it will be there
> when you're done fixing other things. ;-)  Things like making it
> possible in Isearch to handle certain groups of chars (‘ and `,
> for instance) as equivalence classes.  That is a harder nut to
> crack, but also one that is genuinely worthwhile cracking.

Agreed.


        Stefan "Anxiously waiting for your patch"

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Stefan Monnier wrote:
> we need some clever way to type them in with very little effort.

Something like smart-quotes-mode, say?

https://github.com/gareth-rees/smart-quotes

In smart-quotes-mode, if you type this:

    Quoting 'like-this' should look nice.

this is the text you've entered:

    Quoting ‘like-this’ should look nice.

It'd be nice if Emacs had something like that for typing doc strings, along with 
the cleverer searches Drew mentioned.  However, I'm leery of making nifty 
features prerequisites for the most recently proposed patch, as that's a recipe 
for inaction.  Although the proposed patch's new functionality may be harder to 
use than we'd like, progress is made a step at a time and we can add more nifty 
features later.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Mon, 20 Apr 2015 20:45:55 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: 20385@debbugs.gnu.org
> 
> Stefan Monnier wrote:
> > we need some clever way to type them in with very little effort.
> 
> Something like smart-quotes-mode, say?
> 
> https://github.com/gareth-rees/smart-quotes

The solution that mode suggests for spell-checking will not work well
with modern spellers (aspell and hunspell), because they don't have
the curly apostrophe/quote character in their *.aff files' rules, like
they do with the ASCII apostrophe.

So if we want this to become our default, we need changes in
ispell.el, to replace ’ with ' before we sent it to the speller.  Or
maybe recommend users to install *.aff files that already support ’,
assuming such dictionaries exist.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

> So if we want this to become our default, we need changes in
> ispell.el, to replace ’ with ' before we sent it to the speller.  Or
> maybe recommend users to install *.aff files that already support ’,
> assuming such dictionaries exist.

Another approach would be to keep `...' in the files, but use
redisplay/font-lock tricks to display them ‘like-this’.


        Stefan

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Paul Eggert <eggert@cs.ucla.edu>,  20385@debbugs.gnu.org
> Date: Tue, 21 Apr 2015 14:04:59 -0400
> 
> > So if we want this to become our default, we need changes in
> > ispell.el, to replace ’ with ' before we sent it to the speller.  Or
> > maybe recommend users to install *.aff files that already support ’,
> > assuming such dictionaries exist.
> 
> Another approach would be to keep `...' in the files, but use
> redisplay/font-lock tricks to display them ‘like-this’.

Which tricks did you have in mind?  Overlays?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

> Which tricks did you have in mind?  Overlays?

`display' properties.


        Stefan

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: eggert@cs.ucla.edu,  20385@debbugs.gnu.org
> Date: Tue, 21 Apr 2015 15:34:04 -0400
> 
> > Which tricks did you have in mind?  Overlays?
> 
> `display' properties.

Sounds gross.

Moreover, AFAIU people who want to see ‘this’ actually _want_ to see
the u+2018 etc. characters in the file/buffer.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Dmitry Gutov]

On 04/21/2015 10:50 PM, Eli Zaretskii wrote:

 > Moreover, AFAIU people who want to see ‘this’ actually _want_ to see
> the u+2018 etc. characters in the file/buffer.

That's no problem: fontify the source files like that, too.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Tue, 21 Apr 2015 23:01:55 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> 
> On 04/21/2015 10:50 PM, Eli Zaretskii wrote:
> 
>  > Moreover, AFAIU people who want to see ‘this’ actually _want_ to see
> > the u+2018 etc. characters in the file/buffer.
> 
> That's no problem: fontify the source files like that, too.

No, they want the characters to be in the file.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

I will add that one increasingly important use of `...' is that
doc gets copied and pasted to other, non-Emacs environments.

You might think that `...' is "ugly" (and that is the ONLY
reason that's been given so far for changing it), but it has
the distinct advantage that it is a unique way of quoting
that separates itself from both strings ("...") and ordinary
text quoting (curly quotes, double and single).

If you post doc pieces into a context such as Stack Exchange,
for example, you need only change the ' in `...' to `, to
have that new context also, like Emacs, treat the quoted
sexp specially - not a ordinary quoted text.  That is, SE
uses `...` instead of `...', but it does the same thing
Emacs does, to make the result stand out as code and not as
just any old quoted text.

If you change `...' to ordinary curly quoting, you lose
distinguishing what it quotes as code.

Just one more consideration, another reason why the proposed
change is a bad idea, IMHO.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Drew Adams writes:

> I will add that one increasingly important use of `...' is that
> doc gets copied and pasted to other, non-Emacs environments.
>
> You might think that `...' is "ugly" (and that is the ONLY
> reason that's been given so far for changing it), but it has
> the distinct advantage that it is a unique way of quoting
> that separates itself from both strings ("...") and ordinary
> text quoting (curly quotes, double and single).
>
> If you post doc pieces into a context such as Stack Exchange,
> for example, you need only change the ' in `...' to `, to
> have that new context also, like Emacs, treat the quoted
> sexp specially - not a ordinary quoted text.  That is, SE
> uses `...` instead of `...', but it does the same thing
> Emacs does, to make the result stand out as code and not as
> just any old quoted text.
>
> If you change `...' to ordinary curly quoting, you lose
> distinguishing what it quotes as code.
>
> Just one more consideration, another reason why the proposed
> change is a bad idea, IMHO.

I agree with you.

Maybe a compromise could be to add as an alternative syntax `...` (just
like SE or Markdown)? It would then fix the unbalanced quotes issue.

Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > I will add that one increasingly important use of `...' is that
> > doc gets copied and pasted to other, non-Emacs environments.
> >
> > You might think that `...' is "ugly" (and that is the ONLY
> > reason that's been given so far for changing it), but it has
> > the distinct advantage that it is a unique way of quoting
> > that separates itself from both strings ("...") and ordinary
> > text quoting (curly quotes, double and single).
> >
> > If you post doc pieces into a context such as Stack Exchange,
> > for example, you need only change the ' in `...' to `, to
> > have that new context also, like Emacs, treat the quoted
> > sexp specially - not a ordinary quoted text.  That is, SE
> > uses `...` instead of `...', but it does the same thing
> > Emacs does, to make the result stand out as code and not as
> > just any old quoted text.
> >
> > If you change `...' to ordinary curly quoting, you lose
> > distinguishing what it quotes as code.
> >
> > Just one more consideration, another reason why the proposed
> > change is a bad idea, IMHO.
> 
> I agree with you.
> 
> Maybe a compromise could be to add as an alternative syntax `...`
> (just like SE or Markdown)? It would then fix the unbalanced quotes issue.

1. `...` is not as simple to parse (e.g. using regexps) for Emacs
   highlighting etc.

2. But I also realize that I might not have been as clear in that post
as I should have been.  It's not only about the (increasing) need
to be able to copy doc and paste it to other, non-Emacs environments.

The more important point is that Emacs uses `...' as a different
kind of quoting from ordinary text quoting.  It is Emacs's way of
quoting code that is inline (i.e., within ordinary text).

In other doc systems one might use wrap such inline code with, say,
and XML element: <CodeInLine>(forward-char 3)</CodeInLine>.  For
technical doc related to programming, there is typically *some* way
to set off inline code bits, to indicate that they are code, whether
they are keywords or pieces of programs.  Emacs's way has been `...'.

And IMHO, it is a very good way.  Very simple, and amenable to very
simple regexp identification and thus highlighting & retrieval.

If Emacs at some point decides to switch to another code-quoting
mechanism, that's one thing.  But what it definitely should NOT do,
IMO, is to lose code quoting - lose talking about code from a meta
level, and just quote code bits normally, so they become confused
with ordinary text quoting.

That was really the point I was trying to make in my last point.
`...' is for code.  Changing that to '...' loses the ability to
distinguish code from anything else being quoted normally.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Drew Adams wrote:
> If Emacs at some point decides to switch to another code-quoting
> mechanism, that's one thing.  But what it definitely should NOT do,
> IMO, is to lose code quoting

Yes, that makes sense.  The latest iteration of the proposal does that, by 
suggesting that doc strings use curved single quotes ‘like-this’ to quote code. 
  This mechanism is already used in the Emacs 24.5 info files, and it works well 
there.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Paul Eggert writes:

> Drew Adams wrote:
>> If Emacs at some point decides to switch to another code-quoting
>> mechanism, that's one thing.  But what it definitely should NOT do,
>> IMO, is to lose code quoting
>
> Yes, that makes sense.  The latest iteration of the proposal does that, by 
> suggesting that doc strings use curved single quotes ‘like-this’ to quote code. 
>   This mechanism is already used in the Emacs 24.5 info files, and it works well 
> there.

I don't understand how this would better than using backquotes
`like-this` (or even simply keeping it `like-this'):

- Isn't the curved single quote character *really* hard to type? (I
  don't think I even know how to type it on my keyboard).

- Also, aren't curved single quotes only used to display code quotation
  in compiled info files, not in .texinfo sources (by this I mean that
  nobody actually has to type curved quotes)?

Nico

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Nicolas Petton wrote:
> I don't understand how this would better than using backquotes
> `like-this`

Quoting `like-this` still looks ugly, and still misuses grave accent in a way 
that's confusing for people not accustomed to the style.  It's also harder to 
parse unambiguously than a matching pair of distinct quote characters.

> - Isn't the curved single quote character *really* hard to type?

Yes, and Stefan raised that point too.  It should be reasonably easy to fix this 
(though I haven't coded it up yet).

> - aren't curved single quotes only used to display code quotation
>    in compiled info files, not in .texinfo sources

Yes, and partly because of this info-look.el now handles curved single quotes. 
These sorts of changes are inevitable (and shouldn't be that hard) when 
accommodating Emacs to common quoting styles.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Paul Eggert writes:

> Nicolas Petton wrote:
>> I don't understand how this would better than using backquotes
>> `like-this`
>
> Quoting `like-this` still looks ugly

I guess that's just a matter of taste then.  I think it's perfectly
fine, and FWIW it's also a very common way to quote code nowadays.

>> - Isn't the curved single quote character *really* hard to type?
>
> Yes, and Stefan raised that point too.  It should be reasonably easy to fix this 
> (though I haven't coded it up yet).

How? By inserting curved quotes when the user types a single quote (or
another character) in a string in Elisp code?  Wouldn't that be a big
issue in other modes (or even outside of Emacs)?

Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Nicolas Petton wrote:
> inserting curved quotes when the user types a single quote (or
> another character) in a string in Elisp code?  Wouldn't that be a big
> issue in other modes (or even outside of Emacs)?

I don't see why it would need to affect other modes, or affect programs other 
than Emacs.  The idea is to to make it easier for Elisp programmers to put 
curved single quotes into doc strings.  Of course there is a more-general 
problem of making it easier to use curved quotes in arbitrary contexts 
(including contexts outside Emacs), but that problem needn't be solved here.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Paul Eggert writes:

> Nicolas Petton wrote:
>> inserting curved quotes when the user types a single quote (or
>> another character) in a string in Elisp code?  Wouldn't that be a big
>> issue in other modes (or even outside of Emacs)?
>
> I don't see why it would need to affect other modes, or affect
> programs other than Emacs.  The idea is to to make it easier for Elisp
> programmers to put curved single quotes into doc strings.

It's not about affecting other modes, but the fact that quoting code in
elisp docstrings would only be reasonably doable from Emacs' elisp mode,
since curved quotes aren't easy to type.  That could be a problem in
cases like answering elisp question on SE, in an email, etc.

> Of course there is a more-general problem of making it easier to use
> curved quotes in arbitrary contexts (including contexts outside
> Emacs), but that problem needn't be solved here.

I don't think it's worth it to make it unnecessarily hard to write
elisp docstrings anywhere else than in emacs-lisp-mode in Emacs.

It might look like I insist, but something `like-this` looks more than
ok to me:

- it is a really common practice nowadays and most people understand
  what it means.  Many projects use Markdown in their README for
  example;

- it doesn't require to use a special character (understand characters
  that one cannot easily type on a QWERTY keyboard);

- it fixes the "unbalanced" quotes issue that you raised as well as
  using a curved single quote.


But again, I don't see the need for a change at all, and I have never
seen how quoted code looked like in older terminals.

Cheers,
Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

On 04/23/2015 04:15 AM, Nicolas Petton wrote:
> quoting code in
> elisp docstrings would only be reasonably doable from Emacs' elisp mode,

No, they're reasonably doable from any editor that supports smart 
quoting.  Although Emacs doesn't have this option, it's common 
elsewhere, and it shouldn't be that hard to add it to Emacs.

As for quoting `like this` that still doesn't sound like a good idea.  
Do we really want to switch to Markdown (or something like it) for doc 
strings?  That would be a much bigger project, and would be work that 
nobody's prepared to do, and its overall costs could well exceed its 
benefits.

Finally, from this thread it's clear that some folks like quoting `like 
this' and I suppose there's no harm in continuing to support it, so in 
my next iteration of this patch I plan to remove commentary to the 
effect that this usage is obsolescent and may not be supported in the 
future.  So, people who prefer quoting `like this' (e.g., because it's 
easier with their non-Emacs text editors), will still be free to do that.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> Finally, from this thread it's clear that some folks like quoting
> `like this' and I suppose there's no harm in continuing to support it,
> so in my next iteration of this patch I plan to remove commentary to the
> effect that this usage is obsolescent and may not be supported in
> the future.  So, people who prefer quoting `like this' (e.g., because
> it's easier with their non-Emacs text editors), will still be free to do
> that.

1. What exactly do you mean by "people who prefer...will still be free
   to do that"?  Is this choice only at the end-user level?  Can a
   library make such a choice (to be possibly overridden by a user choice)?

2. Does your proposed change affect only Info?  I think that, at the
   very least by default, users should have the same experience wrt such
   code quoting for Info, doc strings, and Emacs-Lisp (doc strings and
   comments).  They should not (at least not by default) see `foobar'
   in a doc string and Emacs-Lisp mode, and ‘foobar’ in Info.

   IOW, a user should be able to make her choice clear wrt such quoting:

   * everywhere, at once (i.e. Info, doc strings, Emacs-Lisp mode)
   * each individual place, separately

3. To repeat myself: I really feel like you are jumping the gun on this
   kind of thing.  We should not offer anything like this, even as a
   choice, unless and until Emacs can deal with it properly (a) in all
   respects: input, search, font-lock,... and (b) everywhere.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

On 04/23/2015 11:23 AM, Drew Adams wrote:
> 1. What exactly do you mean by "people who prefer...will still be free
>     to do that"?  Is this choice only at the end-user level?  Can a
>     library make such a choice (to be possibly overridden by a user choice)?

I mean that Lisp code can use either style in its doc strings, and Emacs 
will work either way.  End users will see what's in the doc string; I'm 
not proposing any on-the-fly reformatting (other than what's already 
there, for limited old displays), as I doubt whether the extra 
complexity would be worth the hassle in the long run.

> 2. Does your proposed change affect only Info?

The proposed change doesn't affect info.  Info files in the Emacs 
distribution already use curved single quotes.  Texinfo files will 
continue to use quotes `like this', to indicate curved single quotes in 
Emacs's info files.  Similarly, quoting ``like this'' in a Texinfo file 
will continue to generate curved double quotes in Emacs's info files.

>     users should have the same experience wrt such
>     code quoting for Info, doc strings, and Emacs-Lisp (doc strings and
>     comments).

Yes, that's the longer term proposal for Emacs's files, using curved 
single quotes.  The current patch is one step in that direction. Under 
this approach, users who prefer to quote `like this' will still be able 
to do that in their own doc strings and manuals.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> Info files in the Emacs distribution already use curved single
> quotes.

I sure hope not.  That's not the case in the Windows binary builds
I was able to download.  But there is no Windows build for the latest
release.  That will certainly be a step backward, if what you say
is true.

> >     users should have the same experience wrt such
> >     code quoting for Info, doc strings, and Emacs-Lisp (doc
> >     strings and comments).
> 
> Yes, that's the longer term proposal for Emacs's files, using curved
> single quotes.

You mean that it is one of your longer-term proposals, I assume.
AFAIK, there is no such longer-term plan published by GNU for
Emacs's files.

Whatever is planned by GNU, I hope it allows users to at least
choose the reliable, conventional system we've enjoyed for 40 years.  
 
> The current patch is one step in that direction.
> Under this approach, users who prefer to quote `like this' will
> still be able to do that in their own doc strings and manuals.

1. You didn't answer my question about libraries being able to
choose (possibly overridden by a user).

2. This sop is not at all sufficient: "able to do that in their
*own* doc strings and manuals".  Might as well say that you will
allow folks to do what they like in their own fork of Emacs.

3. You have still given *no* argument in favor of anything you've
proposed here.  We've seen only the pseudo-argument that you find
the Emacs way "ugly".

IMHO, this self-styled beautification proposal should be
considered a non-starter.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 13:07:14 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20385@debbugs.gnu.org
> 
> > Info files in the Emacs distribution already use curved single
> > quotes.
> 
> I sure hope not.  That's not the case in the Windows binary builds
> I was able to download.  But there is no Windows build for the latest
> release.  That will certainly be a step backward, if what you say
> is true.

This depends on the version of Texinfo used to generate the Info
files.  With the latest version, what Paul says is true.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

On 04/23/2015 01:07 PM, Drew Adams wrote:
> 1. You didn't answer my question about libraries being able to
> choose (possibly overridden by a user).

Sorry if the answer was unclear.  Under the current proposal, a library 
of Emacs Lisp code can choose either style, by using the style in its 
doc strings.  By default, the user will see the library's style.  So 
yes, libraries can choose.  As Eli mentioned, there's a mechanism in 
Emacs to display Unicode characters using approximations on less-capable 
displays, and in that sense the user will be able override a library 
that prefers curved quotes.

> Might as well say that you will
> allow folks to do what they like in their own fork of Emacs.

No, not at all.  Libraries that want to remain easily-editable in older 
versions of Emacs can continue to quote `like this'; their users and 
developers won't need to fork Emacs.

> 3. You have still given*no*  argument in favor of anything you've
> proposed here.  We've seen only the pseudo-argument that you find
> the Emacs way "ugly".

It's not a pseudo argument.  Appearance matters, and the older style is 
off-putting on today's displays.  This is why the GNU coding standards 
recommend against quoting `like this'.  See:

http://www.gnu.org/prep/standards/html_node/Quote-Characters.html

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > This sop is not at all sufficient: "able to do that in their
> > *own* doc strings and manuals".  Might as well say that you will
> > allow folks to do what they like in their own fork of Emacs.
> 
> No, not at all.  Libraries that want to remain easily-editable in
> older versions of Emacs can continue to quote `like this'; their
> users and developers won't need to fork Emacs.

So if someone wants to avoid your change then they have a choice:
fork Emacs or use an older Emacs version.  Wunderbar.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Drew Adams wrote:
> So if someone wants to avoid your change then they have a choice:
> fork Emacs or use an older Emacs version.

Not at all.  People will still be able to use and develop libraries that quote 
`like this' if they want, even if they are using a newer Emacs version.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Paul Eggert writes:

> On 04/23/2015 04:15 AM, Nicolas Petton wrote:
>> quoting code in
>> elisp docstrings would only be reasonably doable from Emacs' elisp mode,
>
> No, they're reasonably doable from any editor that supports smart 
> quoting.  Although Emacs doesn't have this option, it's common 
> elsewhere, and it shouldn't be that hard to add it to Emacs.
>
> As for quoting `like this` that still doesn't sound like a good idea.  
> Do we really want to switch to Markdown (or something like it) for doc 
> strings?  That would be a much bigger project, and would be work that 
> nobody's prepared to do, and its overall costs could well exceed its 
> benefits.

I never suggested adding support for Markdown, I gave Markdown as an
example of `...` being used to quote code.

Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Dmitry Gutov]

On 04/23/2015 08:32 PM, Paul Eggert wrote:

> Finally, from this thread it's clear that some folks like quoting `like
> this' and I suppose there's no harm in continuing to support it, so in
> my next iteration of this patch I plan to remove commentary to the
> effect that this usage is obsolescent and may not be supported in the
> future.  So, people who prefer quoting `like this' (e.g., because it's
> easier with their non-Emacs text editors), will still be free to do that.

Please, let's not have multiple standards for this trivial thing.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > If Emacs at some point decides to switch to another code-quoting
> > mechanism, that's one thing.  But what it definitely should NOT
> > do, IMO, is to lose code quoting
> 
> Yes, that makes sense.  The latest iteration of the proposal does
> that, by suggesting that doc strings use curved single quotes
> ‘like-this’ to quote code.  This mechanism is already used in the
> Emacs 24.5 info files, and it works well there.

Huh?  You say that you agree, that what I say makes sense.  And then
you say that ‘...’ is a solution!  That's precisely what I'm saying
does *not* work.  If you paste that into any context where curly
quoting is used for ordinary text (which - nowadays, as you would say -
means most ordinary-text contexts) then you lose the special quoting
of code.

Whether curly quotes are single or double is irrelevant: both are
used in ordinary situations to quote ordinary text.  Neither is
something special for quoting code.

See http://en.wikipedia.org/wiki/Quotation_mark.  Note, in particular
(in case this was something you were confused about), that British
and American usages tends to be reversed wrt which curly quotes,
single or double, are used at the first level:

 In American English, double quotes are used normally (the "primary"
 style). If quote marks are used inside another pair of quote marks,
 then single quotes are used as the "secondary" style. For example:
 "Didn't she say 'I like red best' when asked her favorite wine?"
 he wondered to himself.

 If another set of quotes is nested, double quotes are used again,
 and they continue to alternate as necessary (though this is rarely
 done). British English tends to have the opposite convention –
 single quotes are primary, and double quotes are secondary.
 Different varieties of English have different rules regarding
 whether neighboring punctuation should be written inside or
 outside the quotation marks.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Drew Adams wrote:
> British
> and American usages tends to be reversed wrt which curly quotes,
> single or double, are used at the first level:

Sure, and the tradition in many GNU projects is to use American-style quoting 
for regular English text, and British-style quoting for code.  For example, the 
Emacs 24.5 manual's info files quote ordinary text like this:

   Emacs occupies a “graphical window”

and quote code like this:

   A description of an imaginary variable, ‘electric-future-map’.

Changing doc strings to look like the latter will better implement the 
longstanding style for documentation in GNU projects.  It's what quoting `like 
this' was originally intended to do (and *did* do, with circa-1965 draft ASCII). 
  It's an eminently reasonable way to quote code in documentation.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > British and American usages tends to be reversed wrt which curly
> > quotes, single or double, are used at the first level:
> 
> Sure, and the tradition in many GNU projects is to use American-
> style quoting for regular English text, and British-style quoting
> for code.  For example, the Emacs 24.5 manual's info files quote
> ordinary text like this:
>    Emacs occupies a “graphical window”
> and quote code like this:
>    A description of an imaginary variable, ‘electric-future-map’.
> 
> Changing doc strings to look like the latter will better implement
> the longstanding style for documentation in GNU projects.  It's what
> quoting `like this' was originally intended to do (and *did* do,
> with circa-1965 draft ASCII).  It's an eminently reasonable way to
> quote code in documentation.

Sorry, but I disagree, whether or not you can claim that it has
been some kind of GNU convention.  It is foolhardy.  Both double
and single curly quotes are used for _ordinary text_ out there in
the real wide world.

Emacs is in that wide world, and increasingly so.  Emacs is a very
general tool, being usable for all sorts of editing and other
activities.  And that includes editing ordinary text.  And ordinary
text that often has embedded code terms.

Sacrificing being able to use two levels of quoting for ordinary
text in favor of stealing one of them for code quoting, just so
that we can wave our hands and say that we respect some old GNU
convention, is quite short-sighted.  Coming from someone who touts
his proposed change as bringing up to "nowadays" and "modern" ways,
I should be surprised.  But I'm not.

In short, Emacs should have all three: single and double curly
quotes for their usual uses with ordinary text, and some reasonable
and distinctive way to quote code that is embedded in ordinary text.

If this were HTML or XML (or even JSON) then we would not be trying
to sacrifice one of the first two for the third.  We would simply
adopt an unmistakable tag for code quoting.

My vote is (clearly) to keep `...' for quoting code in Info,
doc strings, Emacs-Lisp mode,...  It is simple, easy-to-use,
and versatile, and it has proven itself for at least 4 decades.

So far, we have heard exactly ONE (weak) argument against it:
you find it ugly.  I'd say prettify it in your own environment,
if it really bothers you, but otherwise leave it alone.  Let's
not sacrifice the usefulness of this proven convention for
someone's purely cosmetic concerns.

Or was there another argument in favor of your proposed change
that I missed?  I've asked several times now, but have gotten
no reply to the question.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

I said this, which is not clear:

> If this were HTML or XML (or even JSON) then we would not be trying
> to sacrifice one of the first two for the third.  We would simply
> adopt an unmistakable tag for code quoting.

No doubt we do have a similarly unmistakable tag for code quoting,
in TexInfo.

That tag is transformed to `...' in Emacs Info.  If it were transformed
to ‘...’ instead then we would lose the distinction between single-quoted
ordinary text and quoted code.  That's all.

And of course in help (e.g. `C-h f') and in Emacs-Lisp comments and doc
strings, there is no TexInfo representation.

Users should be able to search for a code term foo and not also hit
ordinary text occurrences of foo.  That is approximately possible
today.  And it is simple today to (reasonably, if imperfectly) tell
font-lock to highlight `...' occurrences (as it would be for ‘...’).

In some XML-based editors that provide a WSIWYG view, users can
search specially for a given element (e.g. <CodeInline>) or one with
a given attribute value, while remaining in WYSIWYG.  But that is
a separate search capability from regexp or simple text search in
the same editors.  In Emacs you can easily search for `...' occurrences
and pretty much find what you are looking for.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

On 04/23/2015 07:51 AM, Drew Adams wrote:
> Sacrificing being able to use two levels of quoting for ordinary
> text in favor of stealing one of them for code quoting
That's not what the Emacs info files do.  They prefer American English 
conventions for ordinary text, including quoting “like this” for 
ordinary top-level text.  And they prefer single quoting at the top 
level ‘like-this’ for quoting code.  There's no ambiguity in practice, 
as ordinary quoted text does not quote code in the manuals.  Emacs doc 
strings are similar, so there won't be any ambiguity in practice there 
either.

> No doubt we do have a similarly unmistakable tag for code quoting,
> in TexInfo.

Yes, it's @code{whatever}.

> That tag is transformed to `...' in Emacs Info.

No, @code{foo} is transformed to ‘foo’.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Dmitry Gutov]

On 04/22/2015 10:00 AM, Eli Zaretskii wrote:

>>   > Moreover, AFAIU people who want to see ‘this’ actually _want_ to see
>>> the u+2018 etc. characters in the file/buffer.
>>
>> That's no problem: fontify the source files like that, too.
>
> No, they want the characters to be in the file.

Who are those people, and why do they want that?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 22:55:28 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> 
> On 04/22/2015 10:00 AM, Eli Zaretskii wrote:
> 
> >>   > Moreover, AFAIU people who want to see ‘this’ actually _want_ to see
> >>> the u+2018 etc. characters in the file/buffer.
> >>
> >> That's no problem: fontify the source files like that, too.
> >
> > No, they want the characters to be in the file.
> 
> Who are those people, and why do they want that?

Those who follow Markus Kuhn's advice, read here:

  http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Drew Adams]

> > Who are those people, and why do they want that?
> 
> Those who follow Markus Kuhn's advice, read here:
>   http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

...where the *only* argument given is, again, "it looked rather ugly".
That is the only "why do they want that" that we have heard, so far.

And of course Mr. Kuhn is not specifically talking about an environment
such as Emacs, where you do more with text than just read it.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 13:13:30 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> 
> > > Who are those people, and why do they want that?
> > 
> > Those who follow Markus Kuhn's advice, read here:
> >   http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html
> 
> ...where the *only* argument given is, again, "it looked rather ugly".
> That is the only "why do they want that" that we have heard, so far.

You are missing the point: this paper wants those "rather ugly"
characters to disappear from text content, and not everybody out there
uses Emacs for editing and reading that.  So an Emacs-only solution
that just _shows_ the nice characters, leaving the underlying text
with `..' is not what that paper wants, or preaches for.

> And of course Mr. Kuhn is not specifically talking about an environment
> such as Emacs, where you do more with text than just read it.

He doesn't talk about Emacs at all.  He's talking about the world at
large.  People who want to follow him want the old quoting characters
to never be used at all for quoting purposes.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Dmitry Gutov]

On 04/23/2015 11:03 PM, Eli Zaretskii wrote:

>> Who are those people, and why do they want that?
>
> Those who follow Markus Kuhn's advice, read here:
>
>    http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

I think that's typographical advice, and not necessarily applicable to 
text editors.

It's pretty common to use slightly awkward (but easy to type and 
unambiguous) markup in source code, and then convert it to something 
nicer in generated documentation.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Fri, 24 Apr 2015 06:04:18 +0300
> From: Dmitry Gutov <dgutov@yandex.ru>
> CC: 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> 
> On 04/23/2015 11:03 PM, Eli Zaretskii wrote:
> 
> >> Who are those people, and why do they want that?
> >
> > Those who follow Markus Kuhn's advice, read here:
> >
> >    http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html
> 
> I think that's typographical advice, and not necessarily applicable to 
> text editors.

Nevertheless, many people want Texinfo, Emacs, and GNU in general to
follow that advice.

> It's pretty common to use slightly awkward (but easy to type and 
> unambiguous) markup in source code, and then convert it to something 
> nicer in generated documentation.

I personally have no problem with the traditional `..' quoting style,
I'm just trying to explain why IMO display-time tricks will not
necessarily pacify at least some of those who want the ‘..’ style.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Artur Malabarba]

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

In reply to those worried about how to search for these characters:

If this gets implemented I can finish up the character folding search I was
writing a few months ago. That means searching for regular quotes would
also match curly quotes, just like searching for lowercase strings also
matches upper-case ones (if you have that enabled).

Despite this, I'm completely neutral on whether this should be done or not.

[-- Attachment #2: Type: text/html, Size: 476 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Nicolas Petton]

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


Stefan Monnier writes:

>> So if we want this to become our default, we need changes in
>> ispell.el, to replace ’ with ' before we sent it to the speller.  Or
>> maybe recommend users to install *.aff files that already support ’,
>> assuming such dictionaries exist.
>
> Another approach would be to keep `...' in the files, but use
> redisplay/font-lock tricks to display them ‘like-this’.

I don't see the need for such a change. Is the character ` that ugly?

The way it currently is looks fine to me (and reminds me of the usage of
backquotes in Markdown).

Nico
-- 
Nicolas Petton
http://nicolas-petton.fr

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 512 bytes --]

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Stefan Monnier]

> I don't see the need for such a change. Is the character ` that ugly?

The need is not terribly high, no.
But yes, `...' is ugly.  It used to be pretty back in the XFree86<4.0
days, when they were symmetric, but now they're pretty ugly.

> The way it currently is looks fine to me (and reminds me of the usage of
> backquotes in Markdown).

I've lived with it for 20 years and could live with it another
20 years.  But if someone can provide a good replacement, I'll
accept it.


        Stefan

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Stefan Monnier wrote:
> But yes, `...' is ugly.  It used to be pretty back in the XFree86<4.0
> days, when they were symmetric

And before that, some character-based video display terminals displayed `...' 
nicely.  There was good technical justification for this, as the 1965 draft 
definition of ASCII said 0x27 was the code for an opening single quotation mark. 
  However, standardization headed in a different direction long ago and nowadays 
`...' is ugly everywhere.  For more of the history, please see:

Kuhn M. ASCII and Unicode quotation marks (2007).
http://www.cl.cam.ac.uk/~mgk25/ucs/quotes.html

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

Eli Zaretskii wrote:

> So if we want this to become our default, we need changes in
> ispell.el, to replace ’ with ' before we sent it to the speller.

Although a change like that might make sense, it appears to go beyond what's 
needed for doc strings.  I was thinking of something more modest: change Emacs 
so that if you're editing an Elisp or C string, then when you type `like-this' 
it's by default changed to ‘like-this’.  This would not need to happen 
everywhere, but it would be the default when editing Emacs source code because 
we'd put the appropriate setting into .dir-locals.el.

Or were you thinking about spell-checking doc strings?  If so, I don't see how 
changing the quoting style affects how the spell-checker works.  It wouldn't 
affect the way I spell-check code, anyway.  Could you give an example?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Wed, 22 Apr 2015 16:37:14 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> CC: 20385@debbugs.gnu.org
> 
> Eli Zaretskii wrote:
> 
> > So if we want this to become our default, we need changes in
> > ispell.el, to replace ’ with ' before we sent it to the speller.
> 
> Although a change like that might make sense, it appears to go beyond what's 
> needed for doc strings.

The suggestion to which I responded was to use
https://github.com/gareth-rees/smart-quotes, which is a minor mode
that is not limited to doc strings.  Moreover, it is not limited to
quoting, AFAIU, it will also replace lone apostrophes with ’.

> I was thinking of something more modest: change Emacs 
> so that if you're editing an Elisp or C string, then when you type `like-this' 
> it's by default changed to ‘like-this’.

I don't think you describe smart-quotes, you describe some other
similar feature.  I was talking about smart-quotes, and especially
about making it default in text modes.

> Or were you thinking about spell-checking doc strings?

If you are considering a feature similar to smart-quotes, especially
if it's not limited to quoting, then yes, spell-checking doc strings
will hit the same problem.

> If so, I don't see how changing the quoting style affects how the
> spell-checker works.  It wouldn't affect the way I spell-check code,
> anyway.  Could you give an example?

If this is limited to quoting, I don't think it will affect
spell-checking.  But that's not what I was talking about.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Ivan Shmakov]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

[…]

 > But I've resisted going this way so far because of the difficulty to
 > type those things.  IOW, I think we need some clever way to type them
 > in with very little effort.

	Apart from the already suggested smart-quotes-mode, there’s this
	bit I personally use.  (See also bug#16082.)

(eval-after-load 'iso-transl
  '(iso-transl-define-keys
    '(("\"[" . [?“]) ("\"]" . [?”])
      ("'["  . [?‘]) ("']"  . [?’]))))

key             binding
―――             ―――――――
A-' [		‘
A-' ]		’
A-" [		“
A-" ]		”
C-x 8 ' [	‘
C-x 8 ' ]	’
C-x 8 " [	“
C-x 8 " ]	”

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> From: Ivan Shmakov <ivan@siamics.net>
> Date: Tue, 21 Apr 2015 18:35:53 +0000
> 
> 	Apart from the already suggested smart-quotes-mode, there’s this
> 	bit I personally use.  (See also bug#16082.)
> 
> (eval-after-load 'iso-transl
>   '(iso-transl-define-keys
>     '(("\"[" . [?“]) ("\"]" . [?”])
>       ("'["  . [?‘]) ("']"  . [?’]))))
> 
> key             binding
> ―――             ―――――――
> A-' [		‘
> A-' ]		’
> A-" [		“
> A-" ]		”
> C-x 8 ' [	‘
> C-x 8 ' ]	’
> C-x 8 " [	“
> C-x 8 " ]	”

Why not do what texinfo.el does to insert ``..'' when you press " ?
Isn't that simpler and easier on the user?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Ivan Shmakov]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>>>>> From: Ivan Shmakov  Date: Tue, 21 Apr 2015 18:35:53 +0000

[…]

 >> C-x 8 " [ “
 >> C-x 8 " ] ”

 > Why not do what texinfo.el does to insert ``..'' when you press " ?
 > Isn't that simpler and easier on the user?

	Personally, I prefer for these characters to be available all
	around Emacs, so even if there’re simpler means to enter them in
	some modes, I’d still need 'iso-transl (or the likes of it)
	elsewhere.

	Otherwise, given that texinfo-insert-quote seems to properly
	handle “code sample” vs. “prose” contexts, – yes, this may come
	to be a good enough solution for the problem at hand.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> From: Ivan Shmakov <ivan@siamics.net>
> Date: Tue, 21 Apr 2015 19:37:48 +0000
> 
> >>>>> Eli Zaretskii <eliz@gnu.org> writes:
> >>>>> From: Ivan Shmakov  Date: Tue, 21 Apr 2015 18:35:53 +0000
> 
> […]
> 
>  >> C-x 8 " [ “
>  >> C-x 8 " ] ”
> 
>  > Why not do what texinfo.el does to insert ``..'' when you press " ?
>  > Isn't that simpler and easier on the user?
> 
> 	Personally, I prefer for these characters to be available all
> 	around Emacs, so even if there’re simpler means to enter them in
> 	some modes, I’d still need 'iso-transl (or the likes of it)
> 	elsewhere.

I wasn't necessarily talking about "some modes".  You can make this
customization global, can't you?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Alan Mackenzie]

In article <mailman.1406.1429745828.904.bug-gnu-emacs@gnu.org> you wrote:
> Drew Adams wrote:
>> If Emacs at some point decides to switch to another code-quoting
>> mechanism, that's one thing.  But what it definitely should NOT do,
>> IMO, is to lose code quoting

> Yes, that makes sense.  The latest iteration of the proposal does that, by 
> suggesting that doc strings use curved single quotes ?like-this? to quote code. 
>  This mechanism is already used in the Emacs 24.5 info files, and it works well 
> there.

It doesn't work at all well in my terminal (a Linux virtual tty).
Whatever these characters are, they are displayed as inverse question
marks.  I'm not in favour of proliferating these characters over our code
as well.  How do you type them?  How do you search for them?

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: 23 Apr 2015 12:11:09 -0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: Paul Eggert <eggert@cs.ucla.edu>
> 
> >  This mechanism is already used in the Emacs 24.5 info files, and it works well 
> > there.
> 
> It doesn't work at all well in my terminal (a Linux virtual tty).
> Whatever these characters are, they are displayed as inverse question
> marks.

In Emacs or in the stand-alone Info reader?

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Alan Mackenzie]

Hello, Eli.

On Thu, Apr 23, 2015 at 03:35:15PM +0300, Eli Zaretskii wrote:
> > Date: 23 Apr 2015 12:11:09 -0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: Paul Eggert <eggert@cs.ucla.edu>

> > >  This mechanism is already used in the Emacs 24.5 info files, and it works well 
> > > there.

> > It doesn't work at all well in my terminal (a Linux virtual tty).
> > Whatever these characters are, they are displayed as inverse question
> > marks.

> In Emacs or in the stand-alone Info reader?

In Emacs.  I haven't yet tried it in the stand-alone Info reader.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Eli Zaretskii]

> Date: Thu, 23 Apr 2015 12:45:03 +0000
> Cc: 20385@debbugs.gnu.org, eggert@cs.ucla.edu
> From: Alan Mackenzie <acm@muc.de>
> 
> > > It doesn't work at all well in my terminal (a Linux virtual tty).
> > > Whatever these characters are, they are displayed as inverse question
> > > marks.
> 
> > In Emacs or in the stand-alone Info reader?
> 
> In Emacs.

We can easily fix that, e.g. by using a display table in Info and
*Help* buffers.

> I haven't yet tried it in the stand-alone Info reader.

The next version of Texinfo's Info reader will use ASCII replacements
on text terminals that cannot display these (and other) characters.

Of course, the search issue still remains, you will have to use
"C-x 8 RET", unless we provide commands to insert these characters
directly.

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Alan Mackenzie]

In article <mailman.1407.1429745888.904.bug-gnu-emacs@gnu.org> you wrote:
> Eli Zaretskii wrote:

>> So if we want this to become our default, we need changes in
>> ispell.el, to replace ? with ' before we sent it to the speller.

> Although a change like that might make sense, it appears to go beyond what's 
> needed for doc strings.  I was thinking of something more modest: change Emacs 
> so that if you're editing an Elisp or C string, then when you type `like-this' 
> it's by default changed to ?like-this?.

No.  Please don't do this.  I hate it when proprietary programs pull this
trick.  If you type a self-inserting character, that is what you should get.
Not all uses of ` and ' in strings are for quoting.

Also there are complicated repercussions for searching and matching, and
probably quite a few other things, too.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#20385: [PROPOSED PATCH] Support quoting 'like this' in doc strings

[Paul Eggert]

On 04/23/2015 05:27 AM, Alan Mackenzie wrote:
> I hate it when proprietary programs pull this
> trick.

If we do anything like smartquotes, it should be an option that you can 
turn off, and there should be a more-traditional-but-still-easy way to 
insert curved single quotes.  For the latter, perhaps we could have M-( 
insert "‘’" when in a string or comment.  M-( is already documented to 
have a precondition that point is not in a string or comment, so this 
would be an upward-compatible extension. Or perhaps you could suggest 
better bindings.  This sort of thing might be good enough that we 
wouldn't need smartquotes after all.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

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

Stefan's comment "How does it interact with electric-pair-mode?" in 
<http://bugs.gnu.org/20545#11> prompted me to go back to the patch proposed for 
Bug#20385 and to get it to work with electric-pair-mode as well.  The revised 
patch is attached.  Most of the new revisions are to 
lisp/progmodes/elisp-mode.el.  They also add support for C-M-i completion in the 
presence of curved quotes, and tweak some wording in the documentation.

I haven't installed this as I am still mulling over similar revisions to the 
patch proposed for Bug#20545 (this is to make it easier to type curved quotes in 
doc strings).

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Support-curved-quotes-in-doc-strings.patch --]
[-- Type: text/x-patch; name="0001-Support-curved-quotes-in-doc-strings.patch", Size: 16661 bytes --]

From eb392195ffdb108228c981f92ca8b5766afdcff9 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 13 May 2015 00:10:00 -0700
Subject: [PATCH] Support curved quotes in doc strings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Emacs's traditional doc string style has been to quote symbols
`like this'.  This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better.  Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* 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/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
---
 doc/lispref/tips.texi           | 33 ++++++++++++++++++---------------
 etc/NEWS                        |  4 ++++
 lisp/cedet/srecode/texi.el      |  2 +-
 lisp/emacs-lisp/checkdoc.el     |  5 +++--
 lisp/emacs-lisp/lisp-mode.el    |  8 ++++----
 lisp/finder.el                  |  2 +-
 lisp/gnus/gnus-art.el           |  8 ++++----
 lisp/help-mode.el               |  7 ++++---
 lisp/international/mule-cmds.el |  2 +-
 lisp/progmodes/elisp-mode.el    | 24 +++++++++++++-----------
 lisp/wid-edit.el                |  2 +-
 11 files changed, 54 insertions(+), 43 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..912d746 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -658,17 +658,20 @@ starting double-quote is not part of the string!
 @anchor{Docstring hyperlinks}
 @item
 When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with a grave
-accent @samp{`} before and apostrophe @samp{'} after it.  There are
+would be printed (which usually means in lower case), with surrounding
+it with curved single quotes (@samp{‘} and @samp{’}).  There are
 two exceptions: write @code{t} and @code{nil} without surrounding
-punctuation.  For example: @samp{CODE can be `lambda', nil, or t.}
-(In this manual, we use a different convention, with single-quotes
-around symbols.)
+punctuation.  For example: @samp{CODE can be ‘lambda’, nil, or t.}
+
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @samp{`} and apostrophe
+@samp{'}: @samp{`like-this'} rather than @samp{‘like-this’}.  This
+older convention was designed for now-obsolete displays in which grave
+accent and apostrophe were mirror images.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name between grave accent and apostrophe, if the symbol
-has either a
+uses a single-quoted symbol name, if the symbol has either a
 function or a variable definition.  You do not need to do anything
 special to make use of this feature.  However, when a symbol has both a
 function definition and a variable definition, and you want to refer to
@@ -678,7 +681,7 @@ immediately before the symbol name.  (Case makes no difference in
 recognizing these indicator words.)  For example, if you write
 
 @example
-This function sets the variable `buffer-file-name'.
+This function sets the variable ‘buffer-file-name’.
 @end example
 
 @noindent
@@ -691,7 +694,7 @@ you can write the words @samp{symbol} or @samp{program} before the
 symbol name to prevent making any hyperlink.  For example,
 
 @example
-If the argument KIND-OF-RESULT is the symbol `list',
+If the argument KIND-OF-RESULT is the symbol ‘list’,
 this function returns a list of all the objects
 that satisfy the criterion.
 @end example
@@ -710,21 +713,21 @@ followed by the word @samp{face}.  In that case, only the face
 documentation will be shown, even if the symbol is also defined as a
 variable or as a function.
 
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) between grave accent and apostrophe, preceded by
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
 @samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
 anchor}.  The Info file name defaults to @samp{emacs}.  For example,
 
 @smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+See Info node ‘Font Lock’ and Info node ‘(elisp)Font Lock Basics’.
 @end smallexample
 
-Finally, to create a hyperlink to URLs, write the URL between grave
-accent and apostrophe, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}.  For example,
 
 @smallexample
 The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
+‘http://www.gnu.org/’).
 @end smallexample
 
 @item
diff --git a/etc/NEWS b/etc/NEWS
index 3f907db..817330f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -858,6 +858,10 @@ directory at point.
 *** New macros `thread-first' and `thread-last' allow threading a form
     as the first or last argument of subsequent forms.
 
+** Documentation strings now support quoting with curved single quotes
+‘like-this’ in addition to the old style with grave accent and
+apostrophe `like-this'.  The new style looks better on today's displays.
+
 +++
 ** Time-related changes:
 
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index 5c3f21c..5068b2a 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -253,7 +253,7 @@ that class.
  [ stuff ]  => @code{[ stuff ]}
  Key        => @kbd{Key}     (key is C\\-h, M\\-h, SPC, RET, TAB and the like)
  ...        => @dots{}"
-  (while (string-match "`\\([-a-zA-Z0-9<>.]+\\)'" string)
+  (while (string-match "[`‘]\\([-a-zA-Z0-9<>.]+\\)['’]" string)
     (let* ((vs (substring string (match-beginning 1) (match-end 1)))
 	   (v (intern-soft vs)))
       (setq string
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 777fed0..d6a4c7b 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1554,7 +1554,8 @@ mouse-[0-3]\\)\\)\\>"))
      (save-excursion
        (let ((case-fold-search t)
 	     (ret nil) mb me)
-	 (while (and (re-search-forward "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
+	 (while (and (re-search-forward
+                      "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]" e t)
 		     (not ret))
 	   (let* ((ms1 (match-string 1))
 		  (sym (intern-soft ms1)))
@@ -1824,7 +1825,7 @@ Replace with \"%s\"? " original replace)
 	   nil)))
      ;; t and nil case
      (save-excursion
-       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
+       (if (re-search-forward "\\([`‘]\\(t\\|nil\\)['’]\\)" e t)
 	   (if (checkdoc-autofix-ask-replace
 		(match-beginning 1) (match-end 1)
 		(format "%s should not appear in quotes.  Remove? "
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 108d5cc..476125d 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -405,8 +405,8 @@
        ;; Words inside \\[] tend to be for `substitute-command-keys'.
        ("\\\\\\\\\\[\\(\\(?:\\sw\\|\\s_\\)+\\)\\]"
         (1 font-lock-constant-face prepend))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside ‘’ and `' tend to be symbol names.
+       ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
@@ -454,8 +454,8 @@
        ;; Erroneous structures.
        (,(concat "(" cl-errs-re "\\_>")
         (1 font-lock-warning-face))
-       ;; Words inside `' tend to be symbol names.
-       ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+       ;; Words inside ‘’ and `' tend to be symbol names.
+       ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
         (1 font-lock-constant-face prepend))
        ;; Constant values.
        ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
diff --git a/lisp/finder.el b/lisp/finder.el
index 47fab3c..306f2e2 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -115,7 +115,7 @@ Each element has the form (KEYWORD . DESCRIPTION).")
   "Syntax table used while in `finder-mode'.")
 
 (defvar finder-font-lock-keywords
-  '(("`\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
+  '(("[`‘]\\([^'`‘’]+\\)['’]" 1 font-lock-constant-face prepend))
   "Font-lock keywords for Finder mode.")
 
 (defvar finder-headmark nil
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 989a424..fea89a8 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -7827,11 +7827,11 @@ positives are possible."
     ("/\\([a-z][-a-z0-9]+\\.el\\)\\>[^.?]"
      ;; Exclude [.?] for URLs in gmane.emacs.cvs
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][-a-z0-9]+\\.el\\)'"
+    ("[`‘]\\([a-z][-a-z0-9]+\\.el\\)['’]"
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 8) gnus-button-handle-symbol 1)
-    ("`\\([a-z][a-z0-9]+-[a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 9) gnus-button-handle-symbol 1)
     ("(setq[ \t\n]+\\([a-z][a-z0-9]+-[-a-z0-9]+\\)[ \t\n]+.+)"
      1 (>= gnus-button-emacs-level 7) gnus-button-handle-describe-variable 1)
@@ -7841,7 +7841,7 @@ positives are possible."
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-function 2)
     ("\\b\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>"
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2)
-    ("`\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
+    ("[`‘]\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^'’]+\\)\\)['’]"
      ;; Unlike the other regexps we really have to require quoting
      ;; here to determine where it ends.
      1 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-key 3)
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index d6679e9..cf8ec0c 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -322,7 +322,7 @@ Commands:
 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
 		    "[ \t\n]+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]"))
   "Regexp matching doc string references to symbols.
 
 The words preceding the quoted symbol can be used in doc strings to
@@ -337,11 +337,12 @@ when help commands related to multilingual environment (e.g.,
 
 
 (defconst help-xref-info-regexp
-  (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+  (purecopy
+   "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to an Info node.")
 
 (defconst help-xref-url-regexp
-  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to a URL.")
 
 ;;;###autoload
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index fd892aa..a49e293 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -177,7 +177,7 @@
 		    "\\(charset\\)"
 		    "\\)\\s-+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]")))
 
 (defun coding-system-change-eol-conversion (coding-system eol-type)
   "Return a coding system which differs from CODING-SYSTEM in EOL conversion.
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index e06b920..b070029 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -231,7 +231,7 @@ Blank lines separate paragraphs.  Semicolons start comments.
   (lisp-mode-variables nil nil 'elisp)
   (add-hook 'after-load-functions #'elisp--font-lock-flush-elisp-buffers)
   (setq-local electric-pair-text-pairs
-              (cons '(?\` . ?\') electric-pair-text-pairs))
+              (append '((?\` . ?\') (?‘ . ?’)) electric-pair-text-pairs))
   (setq imenu-case-fold-search nil)
   (add-function :before-until (local 'eldoc-documentation-function)
                 #'elisp-eldoc-documentation-function)
@@ -394,7 +394,7 @@ It can be quoted, or be inside a quoted form."
                ((or (eq (char-after) ?\[)
                     (progn
                       (skip-chars-backward " ")
-                      (memq (char-before) '(?' ?`))))
+                      (memq (char-before) '(?' ?` ?‘))))
                 (setq res t))
                ((eq (char-before) ?,)
                 (setq nesting nil))))
@@ -459,7 +459,7 @@ It can be quoted, or be inside a quoted form."
 	   (beg (condition-case nil
 		    (save-excursion
 		      (backward-sexp 1)
-		      (skip-syntax-forward "'")
+		      (skip-chars-forward "`',‘")
 		      (point))
 		  (scan-error pos)))
 	   (end
@@ -470,7 +470,7 @@ It can be quoted, or be inside a quoted form."
 		  (save-excursion
 		    (goto-char beg)
 		    (forward-sexp 1)
-                    (skip-chars-backward "'")
+                    (skip-chars-backward "'’")
 		    (when (>= (point) pos)
 		      (point)))
 		(scan-error pos))))
@@ -478,7 +478,7 @@ It can be quoted, or be inside a quoted form."
            (funpos (eq (char-before beg) ?\())
            (quoted (elisp--form-quoted-p beg)))
       (when (and end (or (not (nth 8 (syntax-ppss)))
-                         (eq (char-before beg) ?`)))
+                         (memq (char-before beg) '(?` ?‘))))
         (let ((table-etc
                (if (or (not funpos) quoted)
                    ;; FIXME: We could look at the first element of the list and
@@ -901,15 +901,17 @@ If CHAR is not a character, return nil."
 (defun elisp--preceding-sexp ()
   "Return sexp before the point."
   (let ((opoint (point))
-	ignore-quotes
+	(left-quote ?‘)
 	expr)
     (save-excursion
       (with-syntax-table emacs-lisp-mode-syntax-table
-	;; If this sexp appears to be enclosed in `...'
+	;; If this sexp appears to be enclosed in `...' or ‘...’
 	;; then ignore the surrounding quotes.
-	(setq ignore-quotes
-	      (or (eq (following-char) ?\')
-		  (eq (preceding-char) ?\')))
+	(cond ((eq (preceding-char) ?’)
+	       (progn (forward-char -1) (setq opoint (point))))
+	      ((or (eq (following-char) ?\')
+		   (eq (preceding-char) ?\'))
+	       (setq left-quote ?\`)))
 	(forward-sexp -1)
 	;; If we were after `?\e' (or similar case),
 	;; use the whole thing, not just the `e'.
@@ -933,7 +935,7 @@ If CHAR is not a character, return nil."
 	      (forward-sexp -1))))
 
 	(save-restriction
-	  (if (and ignore-quotes (eq (following-char) ?`))
+	  (if (eq (following-char) left-quote)
               ;; vladimir@cs.ualberta.ca 30-Jul-1997: Skip ` in `variable' so
               ;; that the value is returned, not the name.
 	      (forward-char))
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 0a95783..dac3b1e 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2863,7 +2863,7 @@ The following properties have special meanings for this widget:
   :type 'boolean
   :group 'widget-documentation)
 
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "[`‘]\\([^\n `'‘’]+\\)['’]"
   "Regexp for matching potential links in documentation strings.
 The first group should be the link itself."
   :type 'regexp
-- 
2.1.0

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/13/2015 10:30 AM, Paul Eggert wrote:

> I haven't installed this as I am still mulling over similar revisions to
> the patch proposed for Bug#20545 (this is to make it easier to type
> curved quotes in doc strings).

FWIW, this looks bad in Thunderbird's attachment preview. It's most 
likely the email client's fault, but still.

Why don't we want to use straight apostrophes in the source files again? 
And prettify them with font-lock? Or keep the current quoting, and 
likewise prettify it with font-lock?

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

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

Dmitry Gutov wrote:
> Why don't we want to use straight apostrophes in the source files again

‘again’?  Emacs has been using asymmetric quotes in doc strings forever.  Or are 
you referring to the original Bug#20385 proposal of straight apostrophes? 
Stefan wasn't sure he liked that idea, and preferred curved quotes.  I'd be 
happy either way, myself; the point is that those grave accents have got to go.

> Or keep the current quoting, and likewise prettify it with font-lock?

That's been proposed, but nobody has taken the time to do it.  Plus, it'd be One 
More Thing; it's simpler if doc strings are plain strings and are not little 
subsets of Markdown or whatever.

> this looks bad in Thunderbird's attachment preview

It looks OK when I use Thunderbird 31.6.0 in Ubuntu 15.04 in an American English 
locale (first attachment).  It's not a thing of beauty, admittedly, but it's 
legible enough.  It looks much nicer under emacs -Q, which is what counts 
(second attachment).

[-- Attachment #2: Screenshot from 2015-05-13 07:56:47.png --]
[-- Type: image/png, Size: 7686 bytes --]

[-- Attachment #3: Screenshot from 2015-05-13 08:08:51.png --]
[-- Type: image/png, Size: 10990 bytes --]

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/13/2015 06:13 PM, Paul Eggert wrote:

> ‘again’?  Emacs has been using asymmetric quotes in doc strings
> forever.

I mean that the suggestion was voiced but never sufficiently addressed.

> Or are you referring to the original Bug#20385 proposal of
> straight apostrophes? Stefan wasn't sure he liked that idea, and
> preferred curved quotes.  I'd be happy either way, myself; the point is
> that those grave accents have got to go.

The suggestion to use font-lock was Stefan's as well.

> That's been proposed, but nobody has taken the time to do it.  Plus,
> it'd be One More Thing; it's simpler if doc strings are plain strings
> and are not little subsets of Markdown or whatever.

That's trivial, if there's agreement to do it. I don't really understand 
the motivation for the original proposal (to switch away from `...'), so 
it's not clear to me if font-locking would satisfy it.

Also, will going from `...' to '...' be beneficial enough, provided 
font-lock displays both as curly single quotes? The downsides to this 
are obvious (changing habits, re-training contributors).

"Plain" unicode strings are not that plain, especially if it still takes 
4 keypresses to type the character, and I also need to explain to 
contributors how to do that.

> It looks OK when I use Thunderbird 31.6.0 in Ubuntu 15.04 in an American
> English locale (first attachment).  It's not a thing of beauty,
> admittedly, but it's legible enough.  It looks much nicer under emacs
> -Q, which is what counts (second attachment).

That's not a question of aesthetics.

For some reason still unclear to me (I have English locale and language 
set everywhere I can see), it displays a group of cyrillic characters 
(тАШ) instead of the fancy quotes. Which will complicate reading small 
patches somewhat (ones I wouldn't open in an external program otherwise).

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Dmitry Gutov wrote:

> I don't really understand the
> motivation for the original proposal (to switch away from `...'), so it's not
> clear to me if font-locking would satisfy it.

The main motivation is that English text shouldn't use grave accent to quote. 
It looked good decades ago but the underlying encodings changed and now it is 
klunky and offputting.  (It's not as bad as the 1950s syntax 16HTHIS IS A STRING 
but that's a low bar....)  Yes, it was a GNU tradition for many years, but other 
GNU packages (GCC, coreutils, etc.) have largely shifted away from it and it's 
time Emacs made it more convenient to use the more-standard convention of curved 
quotes.

I haven't tried font locking.  As I understand it, though, font locking would 
address the problem only in doc strings.  For example, it wouldn't address 
Emacs's diagnostic messages, which also need to get fixed.  In contrast, the 
sorts of solutions I'm proposing should help support curved quotes nearly 
everywhere.

> "Plain" unicode strings are not that plain, especially if it still takes 4
> keypresses to type the character, and I also need to explain to contributors how
> to do that.

The patch proposed in Bug#20545 largely addresses this problem.  Contributors 
can use the same keypresses as before.  If your contributors type this:

   The value may be `buffered', `retained', or `non-retained'.

the following characters are put into their doc string:

   The value may be ‘buffered’, ‘retained’, or ‘non-retained’.

They won't have to do anything special to get this behavior; just use the 
revised Emacs on its own source code.

> For some reason still unclear to me (I have English locale and language set
> everywhere I can see), it displays a group of cyrillic characters (тАШ) instead
> of the fancy quotes. Which will complicate reading small patches somewhat (ones
> I wouldn't open in an external program otherwise).

I reproduced that problem in Thunderbird by visiting "View > Character Encoding 
 > Auto-Detect" and selecting "Russian".  To fix it, I selected "(off)" instead 
of "Russian".

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/14/2015 06:24 AM, Paul Eggert wrote:

> The main motivation is that English text shouldn't use grave accent to
> quote. It looked good decades ago but the underlying encodings changed
> and now it is klunky and offputting.  (It's not as bad as the 1950s
> syntax 16HTHIS IS A STRING but that's a low bar....)  Yes, it was a GNU
> tradition for many years, but other GNU packages (GCC, coreutils, etc.)
> have largely shifted away from it and it's time Emacs made it more
> convenient to use the more-standard convention of curved quotes.

The other GNU packages have transitioned to using the straight 
apostrophes though, didn't they?

> I haven't tried font locking.  As I understand it, though, font locking
> would address the problem only in doc strings.  For example, it wouldn't
> address Emacs's diagnostic messages, which also need to get fixed.  In
> contrast, the sorts of solutions I'm proposing should help support
> curved quotes nearly everywhere.

The diagnostic messages can be treated differently (use fancy quotes, 
since we know this text will appear to the user as-is), or whatever code 
outputs diagnostics could convert the ASCII quotes to the fancy ones 
on-the-fly.

> The patch proposed in Bug#20545 largely addresses this problem.
> Contributors can use the same keypresses as before.  If your
> contributors type this:

Ah, sorry, that's better. I was under the impression, from a related 
discussion, that we'll need to type something like `C-x 8 ''.

> I reproduced that problem in Thunderbird by visiting "View > Character
> Encoding > Auto-Detect" and selecting "Russian".  To fix it, I selected
> "(off)" instead of "Russian".

Thank you. Indeed, that is it. As a Russian speaker, though, I'm not 
going to turn it off.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Dmitry Gutov wrote:

> The other GNU packages have transitioned to using the straight apostrophes
> though, didn't they?

No, in locales where UTF-8 is allowed these packages typically use curved 
quotes.  Here are GCC and coreutils in my (UTF-8) locale:

   $ echo @ >t.c
   $ gcc t.c
   t.c:1:1: error: stray ‘@’ in program
   $ mv xzzy sfasdf
   mv: cannot stat ‘xzzy’: No such file or directory

The packages do use straight apostrophes in locales that lack curved quotes, but 
such locales are becoming less popular with time.

> The diagnostic messages can be treated differently (use fancy quotes, since we
> know this text will appear to the user as-is)

Sure, but that's more complicated as it'd mean two ways to generate curved 
quotes.  Another way to put it: we'd still need an easy way for users to type 
curved quotes in strings and once we have that (as per the Bug#20545 patch) then 
why not prefer the same easy way to type curved quotes in doc strings?

> As a Russian speaker, though, I'm not going to
> turn it off.

Completely understandable.  I suppose you can turn it off for the odd message 
where that's useful -- a bit awkward, but better than nothing.

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/15/2015 10:49 AM, Paul Eggert wrote:

> No, in locales where UTF-8 is allowed these packages typically use
> curved quotes.  Here are GCC and coreutils in my (UTF-8) locale:

On the other hand, you'll be able to dynamically determine which quotes 
to use, depending e.g. on the locale.

>    $ echo @ >t.c
>    $ gcc t.c
>    t.c:1:1: error: stray ‘@’ in program

It still doesn't have the fancy quotes directly in the source code: they 
seem to be generated dynamically, similarly to the suggestion above:

https://github.com/gcc-mirror/gcc/blob/06fa1266fac43778983b3925ad048748297db38c/gcc/c-family/c-lex.c#L526

> Sure, but that's more complicated as it'd mean two ways to generate
> curved quotes.

Neither of those should be particularly hard to implement.

> Another way to put it: we'd still need an easy way for
> users to type curved quotes in strings and once we have that (as per the
> Bug#20545 patch)

I don't see why we'd still need that, but the patch seems generally 
useful either way.

> then why not prefer the same easy way to type curved
> quotes in doc strings?

Two reasons. Neither of them is big, but the improvement from the 
transition to different quoting method is not huge either.

- Using unicode for markup is a complication (e.g. with certain mail 
clients, but some other instances might come up).
- I don't like having two standards for quoting. And if quotes are 
agumented with font-lock, all the existing Elisp out there will be 
displayed with modern quotes automatically.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

On 05/15/2015 10:24 AM, Dmitry Gutov wrote:
> It still doesn't have the fancy quotes directly in the source code: 
> they seem to be generated dynamically

Yes, GCC uses "%< %>" in format strings to represent curved quotes, and 
Coreutils has a function 'quote (X)' that returns X surrounded by curved 
quotes.  However, these are both awkward compared to just using quotes.  
GCC and Coreutils use these awkward constructs because they can't assume 
decent support for Unicode. Emacs doesn't have this constraint, so it 
can do better.

> On the other hand, you'll be able to dynamically determine which 
> quotes to use, depending e.g. on the locale. 

That's an independent issue: it can be done no matter what quoting 
regime the source code uses.  But it's probably not worth doing 
separately.  Once we're worried about different locales, we'll need to 
translate the strings to Russian (or whatever) and at that point we can 
translate the quotes to use «Russian style».  (And yes, Emacs should do 
this, just as GCC and Coreutils do -- but one thing at a time.)

> Neither of those should be particularly hard to implement.

I'm not that worried about the cost of implementation now.  I'm worried 
about the long-term cost of having a quoting regime that requires 
documentation and explanation.  It's simpler and easier to explain if 
the doc string looks the same in the UI as it does while you're editing 
it.  For example, you can easily cut and paste from the UI into the doc 
string source when composing a new doc string, which is something that 
doesn't work well for either GCC or Coreutils.

> - Using unicode for markup is a complication (e.g. with certain mail 
> clients, but some other instances might come up).

It's a complication we already have, as we already use UTF-8 in a few 
doc strings.  For example, the documentation for prettify-symbols-mode 
uses UTF-8 curved double-quotes.  This usage will naturally grow in 
time.  Yes, there will be some email glitches but they'll be easy to 
iron out as we gain experience.

> - I don't like having two standards for quoting.

Nor do I.  This is a transition process, with the long-term goal of 
quoting via quotes rather than via grave accent and apostrophe. It's not 
practical to do this transition all at once, hence the transition 
period.  But in the long run there'll be just one standard way to quote 
(even if Emacs supports the obsolete way indefinitely).

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/15/2015 09:54 PM, Paul Eggert wrote:

> That's an independent issue: it can be done no matter what quoting
> regime the source code uses.

Terrific. Then there's no need to worry too much about the diagnostic 
messages.

> I'm not that worried about the cost of implementation now.  I'm worried
> about the long-term cost of having a quoting regime that requires
> documentation and explanation.

What's there to explain? Quoting will work as before, it'll only be 
displayed differently (and users could even opt out of that).

> It's simpler and easier to explain if
> the doc string looks the same in the UI as it does while you're editing
> it.

My "lambda"s have been rendered in Greek for quite a while. We even have 
a minor mode for things like this now.

> For example, you can easily cut and paste from the UI into the doc
> string source when composing a new doc string, which is something that
> doesn't work well for either GCC or Coreutils.

Why wouldn't that work in Emacs either way?

The only place that seems like it'll have this problem is the Info 
buffers, but they have a lot of other markup that looks differently in 
the source anyway.

>> - Using unicode for markup is a complication (e.g. with certain mail
>> clients, but some other instances might come up).
>
> It's a complication we already have, as we already use UTF-8 in a few
> doc strings.  For example, the documentation for prettify-symbols-mode
> uses UTF-8 curved double-quotes.

Does it? I can't find that.

But either way, allowing unicode in sources (why we do, obviously) and 
using unicode characters as ubiquitous markup are two very different things.

> Nor do I.  This is a transition process, with the long-term goal of
 > quoting via quotes rather than via grave accent and apostrophe.

If we use rendering via font-lock, there will be no transition process.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

On 05/15/2015 12:09 PM, Dmitry Gutov wrote:
> Then there's no need to worry too much about the diagnostic messages.
>

No, that doesn't follow.  For example, suppose that the display supports 
curved quotes (the typical case) but we use some other format in the 
source code.  Then, cutting from diagnostic output and pasting into the 
source code won't be intuitive and won't work without some Rube Goldberg 
conversion.

In contrast, if we use curved quotes in the source, cutting and pasting 
will work naturally.  It's true that here if the display doesn't support 
curved quotes (the atypical case) then cutting and pasting may not work 
-- but that's not a problem we need to worry about, since it's rare 
nowadays particularly among developers.

> What's there to explain? Quoting will work as before, it'll only be 
> displayed differently (and users could even opt out of that).

That will all require explanation, indefinitely.  And this won't be as 
easy as one might think, particularly if opt-out is common.

>> For example, you can easily cut and paste from the UI into the doc
>> string source when composing a new doc string, which is something that
>> doesn't work well for either GCC or Coreutils.
>
> Why wouldn't that work in Emacs either way?

I suppose it might work in some cases (killing and yanking within a 
single GUI Emacs, say) but not in others (cutting from one Emacs running 
remotely under gnome-terminal and pasting into another in a different 
locale).  The other cases are common enough that they will be a 
continuing hassle.

> The only place that seems like it'll have this problem is the Info buffers

This sounds backwards.  Even now, one can cut curved quotes from an Info 
file and paste them into a .texi file and it will work, on a typical 
system with proper UTF-8 support (and assuming the latest Emacs on the 
master branch and Texinfo 5).  (Just to be clear, I'm not proposing that 
we switch to this .texi style now -- it's not needed for proper use of 
grave accent and apostrophe in our documentation, and so it's a separate 
thing that can be deferred for many years.)

>> For example, the documentation for prettify-symbols-mode
>> uses UTF-8 curved double-quotes.
>
> Does it? I can't find that.

Sorry, I meant tildify-space.  (I mixed up functions: 
prettify-symbols-mode uses a different Unicode character, namely ≤.)

> But either way, allowing unicode in sources (why we do, obviously) and 
> using unicode characters as ubiquitous markup are two very different 
> things.

Yes, they are different in terms of degree.  The existing minor uses of 
UTF-8 in doc strings are merely evidence that UTF-8 works in doc 
strings.  Had these uses been there 20 years or go, or even 10, we would 
have had significant problems in practice; but nowadays, UTF-8 is not a 
problem.

> If we use rendering via font-lock, there will be no transition process.

I'm not so sure, given the cutting-and-pasting issues mentioned above.  
But even if you're right there would still be a tradeoff: would we want 
a trivial transition now to a complex and klunky approach long-term, or 
a nontrivial transition now to a simple and intuitive approach 
long-term?  Let's strive for simplicity.

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/16/2015 12:13 AM, Paul Eggert wrote:

> In contrast, if we use curved quotes in the source, cutting and pasting
> will work naturally.  It's true that here if the display doesn't support
> curved quotes (the atypical case) then cutting and pasting may not work
> -- but that's not a problem we need to worry about, since it's rare
> nowadays particularly among developers.

What if the locale mandates the use of some other kind of quotes? Then 
copying and pasting won't work anyway.

In any case, I've never had a need to copy a diagnostic message with the 
intention to paste it into the source code. Web search or bug report? 
Sure, but never that.

> That will all require explanation, indefinitely.  And this won't be as
> easy as one might think, particularly if opt-out is common.

I've never noticed turning lambda into λ while rendering to be a 
significant problem among users, as long as copy and paste works.

> I suppose it might work in some cases (killing and yanking within a
> single GUI Emacs, say) but not in others (cutting from one Emacs running
> remotely under gnome-terminal and pasting into another in a different
> locale).  The other cases are common enough that they will be a
> continuing hassle.

Again, if there are different locales involved, and you intend to honor 
their different quotings, copying and pasting won't work anyway.

Actually, it's a decent argument against using *any particular locale's* 
quoting, in order not to confuse casual contributors, who'd have to know 
that *these* fancy quotes will be localized, but *those* - won't.

> This sounds backwards.  Even now, one can cut curved quotes from an Info
> file and paste them into a .texi file and it will work, on a typical
> system with proper UTF-8 support (and assuming the latest Emacs on the
> master branch and Texinfo 5).

Maybe you could paste quotes, but not any other kind of formatting. So 
nobody will be too surprised that you can't, in general, paste quotes too.

> Sorry, I meant tildify-space.  (I mixed up functions:
> prettify-symbols-mode uses a different Unicode character, namely ≤.)

Yes, it does - as a part of content, not markup.

And you can notice that if we delimited docstrings with curly quotes 
instead of the straight quotation marks, tildify-space wouldn't have 
been able to use them exactly this way inside the docstring.

> Had these uses been there 20 years or go, or even 10, we would
> have had significant problems in practice; but nowadays, UTF-8 is not a
> problem.

I know of no serious markup language that utilizes unicode, even now.

> I'm not so sure, given the cutting-and-pasting issues mentioned above.
> But even if you're right there would still be a tradeoff: would we want
> a trivial transition now to a complex and klunky approach long-term, or
> a nontrivial transition now to a simple and intuitive approach
> long-term?  Let's strive for simplicity.

Guess I don't see it as clunky. Using ASCII in markup and rendering in 
to something fancier later is fairly common approach.

And the benefits are marginal either way. We have bigger difficulties 
(how to delimit code blocks in docstrings and comments, for instance), 
but here we are discussing changing something that has been working fine 
for years.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Dmitry Gutov wrote:

> What if the locale mandates the use of some other kind of quotes? Then copying
> and pasting won't work anyway.

Yes it will.  It'll work fine.  If a documentation string is in (say) Hungarian, 
a user will be able to paste quoted Hungarian text into it, and the text will 
carry its Hungarian quotation marks along.  It'll be just like documentation in 
English and with English quotes.

> I've never had a need to copy a diagnostic message with the
> intention to paste it into the source code.

Shrug.  I've done it.  And vice versa.  And there are other examples.  The point 
is that it's simpler and nicer if cutting and pasting Just Works.

> Actually, it's a decent argument against using *any particular locale's*
> quoting, in order not to confuse casual contributors, who'd have to know that
> *these* fancy quotes will be localized, but *those* - won't.

No, there's normally no need to localize those curved quotes, not if the text is 
English and uses English quoting.  The only time one would need to localize is 
for obsolete displays lacking curved quotes, which casual contributors are 
unlikely to be using nowadays anyway.

> Maybe you could paste quotes, but not any other kind of formatting.

First, that's not true: many other kinds of formatting (though obviously not 
all) can also be cut and pasted from info into .texi files.  Second, even if it 
were true it'd be OK.  One improvement at a time.  Quotes are such a common kind 
of formatting that simplifying their cutting and pasting is worth doing even if 
we can't simplify all forms of formatting.

> And you can notice that if we delimited docstrings with curly quotes instead of
> the straight quotation marks, tildify-space wouldn't have been able to use them
> exactly this way inside the docstring.

That's not a significant problem, as it applies to any convention that uses only 
paired quotes.  For example, the current documentation for 
skeleton-pair-insert-maybe says "These are (), [], {}, <> and `' ...", and the 
reader needs to infer that those instances of ` and ' are not quotes, but are 
characters.  This sort of thing happens every now and then in documentation, and 
it's no big deal.

> I know of no serious markup language that utilizes unicode, even now.

Texinfo does.  Unicode curved quotes are part of the markup.  They affect 
spacing among other things.

> I don't see it as clunky

That's the main point of disagreement here.  Although Emacs old-timers are used 
to quoting `like this', to newbies it's a weird and offputting relic from 
ancient history.

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/16/2015 02:52 AM, Paul Eggert wrote:

> Yes it will.  It'll work fine.  If a documentation string is in (say)
> Hungarian, a user will be able to paste quoted Hungarian text into it,
> and the text will carry its Hungarian quotation marks along.  It'll be
> just like documentation in English and with English quotes.

I see. But will elisp-completion-at-point detect that point is inside 
the Hungarian quotes now? Will we have to enumerate every possible kind 
of quote in its implementation?

> The point is that it's simpler and nicer if cutting and pasting Just Works.

Ok, we can say it's the main benefit. I think it's not of the utmost 
importance, though.

> No, there's normally no need to localize those curved quotes, not if the
> text is English and uses English quoting.  The only time one would need
> to localize is for obsolete displays lacking curved quotes, which casual
> contributors are unlikely to be using nowadays anyway.

And that localization code will have to deal with every kind of quote, then?

> Texinfo does.  Unicode curved quotes are part of the markup.  They
> affect spacing among other things.

Okay, that's... weird. Any other examples, such as ones that newcomers 
to Emacs might be familiar with?

>> I don't see it as clunky
>
> That's the main point of disagreement here.  Although Emacs old-timers
> are used to quoting `like this', to newbies it's a weird and offputting
> relic from ancient history.

That's neither here nor there. Like you said, they'd still be typing ` 
and ', but in your case those will be converted into actual quote 
characters on the fly, and in mine, only rendered as such.

The end result, visually, would be the same.

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/16/2015 02:52 AM, Paul Eggert wrote:

> Although Emacs old-timers
> are used to quoting `like this', to newbies it's a weird and offputting
> relic from ancient history.

And as long as we're discussing newbies, how about switching to 
Markdown-style quoting, then? Two backticks for inline code reference, a 
pair of triple backticks for a code block.

That's definitely going to be familiar.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Dmitry Gutov wrote:
> how about switching to Markdown-style quoting, then?
> That's definitely going to be familiar.

Familiar to those who know Markdown, yes.  However, English quoting is more 
familiar to English writers, and far more people know English than know both 
English and Markdown.

> will elisp-completion-at-point detect that point is inside the Hungarian quotes

It could easily do so, in a Hungarian locale.  The characters are programmable.

> that's... weird.

It's not weird.  It's ordinary English markup.  It's "weird" only to Emacs and 
TeX users accustomed to oddball quoting `like this' that exists mostly because 
of a historical accident.

> The end result, visually, would be the same.

We don't care only about what appears in Emacs after one types C-h.  Emacs is 
more than just a documentation viewer; it's a tool for editing documentation, 
and to those of us who write documentation (or who view Elisp source code, etc., 
etc.) what we see on the screen when we're editing is important.  (Otherwise 
we'd probably be editing SGML by hand, eeeyyyucckkk.)

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/16/2015 04:48 AM, Paul Eggert wrote:

> Familiar to those who know Markdown, yes.  However, English quoting is
> more familiar to English writers, and far more people know English than
> know both English and Markdown.

How many of them are used to seeing a fancy quote after typing a backtick?

On the other hand, I've noticed that users familiar with Markdown 
consider the `' situation normal, if they treat it like markup (not 
punctuation).

> It could easily do so, in a Hungarian locale.  The characters are
> programmable.

We can do virtually anything. But it's a complication.

> It's not weird.  It's ordinary English markup.

No, it's punctuation, not markup. There's no markup in English.

>> The end result, visually, would be the same.
>
> We don't care only about what appears in Emacs after one types C-h.

I'm not talking about that.

> what we see on the screen when we're
> editing is important.  (Otherwise we'd probably be editing SGML by hand,
> eeeyyyucckkk.)

Indeed, you will see the fancy quotes on the screen while editing source 
files, even if something else will get saved to disk. font-lock is handy 
that way.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

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

On 05/16/2015 01:27 AM, Dmitry Gutov wrote:
> Indeed, you will see the fancy quotes on the screen while editing 
> source files, even if something else will get saved to disk. font-lock 
> is handy that way. 

OK, I tried that, but it didn't work for me.  The attached patch works 
much of the time, but it causes annoying glitches on the screen (for an 
example see attached, created by "emacs -Q" and 'C-h b'; note the red 
color glitch after the double-quote).  Fiddling with the regexp doesn't 
help matters.  I'm afraid that font locking is so poorly documented (see 
Bug#20613) that I can't tell whether the color glitch is a bug in Emacs 
or in this patch's change to Emacs.

Even if I ignore the glitches, I found it disconcerting that the "wrong" 
characters were used to display text characters (or, from another point 
of view, that the buffer's contents were "wrong" compared to what was on 
the screen).  So I'm inclined to do something less tricky, e.g., simply 
replace characters in the *Help* buffer before displaying the buffer.  I 
plan to look into that next.

[-- Attachment #2: fontlockquote.txt --]
[-- Type: text/plain, Size: 689 bytes --]

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index f99e916..4f53509 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -287,6 +287,12 @@ Commands:
 \\{help-mode-map}"
   (set (make-local-variable 'revert-buffer-function)
        'help-mode-revert-buffer)
+  (font-lock-add-keywords
+   nil '(("`\\([^[:space:]'`‘’][^'`‘’]*\\)?'"
+          . (0 (progn (compose-region (match-beginning 0)
+                                      (1+ (match-beginning 0)) ?‘)
+                      (compose-region (1- (match-end 0)) (match-end 0) ?’)
+                      nil)))))
   (set (make-local-variable 'bookmark-make-record-function)
        'help-bookmark-make-record))
 

[-- Attachment #3: Screenshot from 2015-05-19 15:26:13.png --]
[-- Type: image/png, Size: 78652 bytes --]

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/20/2015 02:27 AM, Paul Eggert wrote:
> OK, I tried that, but it didn't work for me.  The attached patch works
> much of the time, but it causes annoying glitches on the screen (for an
> example see attached, created by "emacs -Q" and 'C-h b'; note the red
> color glitch after the double-quote).

That's how a string is highlighted. :) You can press C-u C-x = to see 
which face is used there.

So apparently, font-lock-add-keywords turns on font-lock-mode, and since 
it's never set up in help-mode otherwise, syntactic fontification is 
used (and " is a string delimiter in the standard syntax table). Adding 
this (t is the key) before the call resolves that:

   (setq font-lock-defaults '(nil t))

But in a major mode, I think you're expected to apply all font-lock 
settings via setting font-lock-defaults, not by using 
font-lock-add-keywords (the format of keywords is the same).

> Even if I ignore the glitches, I found it disconcerting that the "wrong"
> characters were used to display text characters (or, from another point
> of view, that the buffer's contents were "wrong" compared to what was on
> the screen).

That shouldn't matter much in a read-only buffer...

> So I'm inclined to do something less tricky, e.g., simply
> replace characters in the *Help* buffer before displaying the buffer.  I
> plan to look into that next.

...but indeed, this approach could be the simpler one.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

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

Dmitry Gutov wrote:
> ...but indeed, this approach could be the simpler one.

I hacked at this a bit, and found that the simpler approach also was better at 
not curving quotes that shouldn't be curved.  For example, describe-variable 
should curve the quotes in the doc string, but not in the contents of the 
variable.  I'm sure this could all be done with font locking but it's simpler to 
just edit the characters.  And I found a reasonably simple way to put it in, 
namely, to modify substitute-command-keys so that it substitutes quotes as well, 
with a simple rule that can be done in one pass with only auxiliary boolean flag.

Revised patches are attached.  The first one changes substitute-command-keys. 
The second one changes the rest of the infrastructure to match; it contains the 
bulk of the previously-proposed changes.  And the third one updates a few doc 
strings, mostly so that ` isn't turned into ‘ when it's really intended to be a 
grave accent.

[-- Attachment #2: 0001-substitute-command-keys-now-curves-quotes.txt --]
[-- Type: text/plain, Size: 6254 bytes --]

From 123615174930c73bdf3a400ad0d45afbcf51316b Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 20 May 2015 22:32:38 -0700
Subject: [PATCH 1/3] substitute-command-keys now curves quotes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

So, for example, it turns "`abc'" into "‘abc’" (Bug#20385).
* doc/lispref/help.texi (Keys in Documentation):
* etc/NEWS: Document this.
* src/doc.c (Fsubstitute_command_keys): Implement it.
---
 doc/lispref/help.texi | 22 +++++++++++++++-------
 etc/NEWS              |  6 ++++++
 src/doc.c             | 39 +++++++++++++++++++++++++++++++++------
 3 files changed, 54 insertions(+), 13 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 868d284..ce29f3f 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -318,10 +318,18 @@ stands for no text itself.  It is used only for a side effect: it
 specifies @var{mapvar}'s value as the keymap for any following
 @samp{\[@var{command}]} sequences in this documentation string.
 
+@item `
+(grave accent) stands for a left single quotation mark (@samp{‘}).
+
+@item '
+(apostrophe) stands for a right single quotation mark (@samp{’}) if
+preceded by grave accent and there are no intervening apostrophes.
+Otherwise, apostrophe stands for itself.
+
 @item \=
-quotes the following character and is discarded; thus, @samp{\=\[} puts
-@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
-output.
+quotes the following character and is discarded; thus, @samp{\=`} puts
+@samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output,
+and @samp{\=\=} puts @samp{\=} into the output.
 @end table
 
 @strong{Please note:} Each @samp{\} must be doubled when written in a
@@ -354,8 +362,8 @@ specifies a key binding that the command does not actually have.
 @smallexample
 @group
 (substitute-command-keys
-   "To abort recursive edit, type: \\[abort-recursive-edit]")
-@result{} "To abort recursive edit, type: C-]"
+   "To abort recursive edit, type ‘\\[abort-recursive-edit]’.")
+@result{} "To abort recursive edit, type ‘C-]’."
 @end group
 
 @group
@@ -376,8 +384,8 @@ C-g             abort-recursive-edit
 @group
 (substitute-command-keys
    "To abort a recursive edit from the minibuffer, type\
-\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
-@result{} "To abort a recursive edit from the minibuffer, type C-g."
+`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
+@result{} "To abort a recursive edit from the minibuffer, type ‘C-g’."
 @end group
 @end smallexample
 
diff --git a/etc/NEWS b/etc/NEWS
index 2540756..ce08881 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -781,6 +781,12 @@ when signaling a file error.  For example, it now reports "Permission
 denied" instead of "permission denied".  The old behavior was problematic
 in languages like German where downcasing rules depend on grammar.
 
+** (substitute-command-keys "`foo'") now returns "‘foo’".
+That is, it replaces grave accents by left single quotation marks, and
+apostrophes that match grave accents by right single quotation marks.
+As before, isolated apostrophes and characters preceded by \= are
+output as-is.
+
 +++
 ** The character classes [:alpha:] and [:alnum:] in regular expressions
 now match multibyte characters using Unicode character properties.
diff --git a/src/doc.c b/src/doc.c
index 8b18fb0..32d6556 100644
--- a/src/doc.c
+++ b/src/doc.c
@@ -693,15 +693,21 @@ summary).
 
 Each substring of the form \\=\\<MAPVAR> specifies the use of MAPVAR
 as the keymap for future \\=\\[COMMAND] substrings.
-\\=\\= quotes the following character and is discarded;
-thus, \\=\\=\\=\\= puts \\=\\= into the output, and \\=\\=\\=\\[ puts \\=\\[ into the output.
+
+Each \\=` is replaced by ‘.  Each ' preceded by \\=` and without
+intervening ' is replaced by ’.
+
+\\=\\= quotes the following character and is discarded; thus,
+\\=\\=\\=\\= puts \\=\\= into the output, \\=\\=\\=\\[ puts \\=\\[ into the output, and
+\\=\\=\\=` puts \\=` into the output.
 
 Return the original STRING if no substitutions are made.
 Otherwise, return a new string.  */)
   (Lisp_Object string)
 {
   char *buf;
-  bool changed = 0;
+  bool changed = false;
+  bool in_quote = false;
   unsigned char *strp;
   char *bufp;
   ptrdiff_t idx;
@@ -734,6 +740,12 @@ Otherwise, return a new string.  */)
   keymap = Voverriding_local_map;
 
   bsize = SBYTES (string);
+
+  /* Add some room for expansion due to quote replacement.  */
+  enum { EXTRA_ROOM = 20 };
+  if (bsize <= STRING_BYTES_BOUND - EXTRA_ROOM)
+    bsize += EXTRA_ROOM;
+
   bufp = buf = xmalloc (bsize);
 
   strp = SDATA (string);
@@ -743,7 +755,7 @@ Otherwise, return a new string.  */)
 	{
 	  /* \= quotes the next character;
 	     thus, to put in \[ without its special meaning, use \=\[.  */
-	  changed = 1;
+	  changed = true;
 	  strp += 2;
 	  if (multibyte)
 	    {
@@ -766,7 +778,6 @@ Otherwise, return a new string.  */)
 	  ptrdiff_t start_idx;
 	  bool follow_remap = 1;
 
-	  changed = 1;
 	  strp += 2;		/* skip \[ */
 	  start = strp;
 	  start_idx = start - SDATA (string);
@@ -833,7 +844,6 @@ Otherwise, return a new string.  */)
 	  Lisp_Object earlier_maps;
 	  ptrdiff_t count = SPECPDL_INDEX ();
 
-	  changed = 1;
 	  strp += 2;		/* skip \{ or \< */
 	  start = strp;
 	  start_idx = start - SDATA (string);
@@ -903,6 +913,7 @@ Otherwise, return a new string.  */)
 	  length = SCHARS (tem);
 	  length_byte = SBYTES (tem);
 	subst:
+	  changed = true;
 	  {
 	    ptrdiff_t offset = bufp - buf;
 	    if (STRING_BYTES_BOUND - length_byte < bsize)
@@ -916,6 +927,22 @@ Otherwise, return a new string.  */)
 	    strp = SDATA (string) + idx;
 	  }
 	}
+      else if (strp[0] == '`')
+	{
+	  in_quote = true;
+	  start = (unsigned char *) "\xE2\x80\x98"; /* ‘ */
+	subst_quote:
+	  length = 1;
+	  length_byte = 3;
+	  idx = strp - SDATA (string) + 1;
+	  goto subst;
+	}
+      else if (strp[0] == '\'' && in_quote)
+	{
+	  in_quote = false;
+	  start = (unsigned char *) "\xE2\x80\x99"; /* ’ */
+	  goto subst_quote;
+	}
       else if (! multibyte)		/* just copy other chars */
 	*bufp++ = *strp++, nchars++;
       else
-- 
2.1.0


[-- Attachment #3: 0002-Support-curved-quotes-in-doc-strings.txt --]
[-- Type: text/plain, Size: 43913 bytes --]

From 715d6f1fc30dd30982ef6d03fc3ec61b826f9513 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 20 May 2015 23:52:35 -0700
Subject: [PATCH 2/3] Support curved quotes in doc strings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Emacs's traditional doc string style has been to quote symbols
`like this'.  This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better.  Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* 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):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
---
 doc/lispref/tips.texi           | 35 +++++++++++++++------------
 etc/NEWS                        |  6 +++++
 lisp/cedet/mode-local.el        | 17 +++++++-------
 lisp/cedet/srecode/texi.el      |  2 +-
 lisp/cus-theme.el               |  6 ++---
 lisp/descr-text.el              |  6 ++---
 lisp/emacs-lisp/checkdoc.el     | 20 +++++++++-------
 lisp/emacs-lisp/cl-generic.el   |  4 ++--
 lisp/emacs-lisp/eieio-opt.el    | 20 ++++++++--------
 lisp/emacs-lisp/lisp-mode.el    |  8 +++----
 lisp/emacs-lisp/package.el      |  6 ++---
 lisp/faces.el                   | 15 ++++++------
 lisp/finder.el                  |  2 +-
 lisp/gnus/gnus-art.el           |  8 +++----
 lisp/help-fns.el                | 52 +++++++++++++++++++++--------------------
 lisp/help-mode.el               |  7 +++---
 lisp/help.el                    |  5 ++--
 lisp/international/mule-cmds.el | 11 +++++----
 lisp/international/mule-diag.el | 15 ++++++------
 lisp/progmodes/elisp-mode.el    | 24 ++++++++++---------
 lisp/wid-edit.el                |  2 +-
 21 files changed, 147 insertions(+), 124 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..798b670 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -658,17 +658,22 @@ starting double-quote is not part of the string!
 @anchor{Docstring hyperlinks}
 @item
 When a documentation string refers to a Lisp symbol, write it as it
-would be printed (which usually means in lower case), with a grave
-accent @samp{`} before and apostrophe @samp{'} after it.  There are
+would be printed (which usually means in lower case), surrounding
+it with curved single quotes (@samp{‘} and @samp{’}).  There are
 two exceptions: write @code{t} and @code{nil} without surrounding
-punctuation.  For example: @samp{CODE can be `lambda', nil, or t.}
-(In this manual, we use a different convention, with single-quotes
-around symbols.)
+punctuation.  For example: @samp{CODE can be ‘lambda’, nil, or t.}
+
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @samp{`} and apostrophe
+@samp{'}: @samp{`like-this'} rather than @samp{‘like-this’}.  This
+older convention was designed for now-obsolete displays in which grave
+accent and apostrophe were mirror images.  Documentation in this older
+convention is converted to the standard convention when it is copied
+into a help buffer.  @xref{Keys in Documentation}.
 
 @cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name between grave accent and apostrophe, if the symbol
-has either a
+uses a single-quoted symbol name, if the symbol has either a
 function or a variable definition.  You do not need to do anything
 special to make use of this feature.  However, when a symbol has both a
 function definition and a variable definition, and you want to refer to
@@ -678,7 +683,7 @@ immediately before the symbol name.  (Case makes no difference in
 recognizing these indicator words.)  For example, if you write
 
 @example
-This function sets the variable `buffer-file-name'.
+This function sets the variable ‘buffer-file-name’.
 @end example
 
 @noindent
@@ -691,7 +696,7 @@ you can write the words @samp{symbol} or @samp{program} before the
 symbol name to prevent making any hyperlink.  For example,
 
 @example
-If the argument KIND-OF-RESULT is the symbol `list',
+If the argument KIND-OF-RESULT is the symbol ‘list’,
 this function returns a list of all the objects
 that satisfy the criterion.
 @end example
@@ -710,21 +715,21 @@ followed by the word @samp{face}.  In that case, only the face
 documentation will be shown, even if the symbol is also defined as a
 variable or as a function.
 
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) between grave accent and apostrophe, preceded by
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
 @samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
 anchor}.  The Info file name defaults to @samp{emacs}.  For example,
 
 @smallexample
-See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
+See Info node ‘Font Lock’ and Info node ‘(elisp)Font Lock Basics’.
 @end smallexample
 
-Finally, to create a hyperlink to URLs, write the URL between grave
-accent and apostrophe, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}.  For example,
 
 @smallexample
 The home page for the GNU project has more information (see URL
-`http://www.gnu.org/').
+‘http://www.gnu.org/’).
 @end smallexample
 
 @item
diff --git a/etc/NEWS b/etc/NEWS
index ce08881..3b6e6f1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -887,6 +887,12 @@ directory at point.
 *** New macros `thread-first' and `thread-last' allow threading a form
     as the first or last argument of subsequent forms.
 
+** Documentation strings now support quoting with curved single quotes
+‘like-this’ in addition to the old style with grave accent and
+apostrophe `like-this'.  The new style looks better on today's displays.
+When an old-style string is copied to a help buffer it is converted to
+the new style.
+
 +++
 ** Time-related changes:
 
diff --git a/lisp/cedet/mode-local.el b/lisp/cedet/mode-local.el
index 3c176ae..3536333 100644
--- a/lisp/cedet/mode-local.el
+++ b/lisp/cedet/mode-local.el
@@ -598,15 +598,16 @@ PROMPT, INITIAL, HIST, and DEFAULT are the same as for `completing-read'."
 (defun overload-docstring-extension (overload)
   "Return the doc string that augments the description of OVERLOAD."
   (let ((doc "\n\This function can be overloaded\
- with `define-mode-local-override'.")
+ with ‘define-mode-local-override’.")
         (sym (overload-obsoleted-by overload)))
     (when sym
-      (setq doc (format "%s\nIt has made the overload `%s' obsolete since %s."
+      (setq doc (format "%s\nIt has made the overload ‘%s’ obsolete since %s."
                         doc sym (get sym 'overload-obsoleted-since))))
     (setq sym (overload-that-obsolete overload))
     (when sym
-      (setq doc (format "%s\nThis overload is obsolete since %s;\nUse `%s' instead."
-                        doc (get overload 'overload-obsoleted-since) sym)))
+      (setq doc (format
+                 "%s\nThis overload is obsolete since %s;\nuse ‘%s’ instead."
+                 doc (get overload 'overload-obsoleted-since) sym)))
     doc))
 
 (defun mode-local-augment-function-help (symbol)
@@ -629,9 +630,9 @@ SYMBOL is a function that can be overridden."
 (defun mode-local-print-binding (symbol)
   "Print the SYMBOL binding."
   (let ((value (symbol-value symbol)))
-    (princ (format "\n     `%s' value is\n       " symbol))
+    (princ (format "\n     ‘%s’ value is\n       " symbol))
     (if (and value (symbolp value))
-        (princ (format "`%s'" value))
+        (princ (format "‘%s’" value))
       (let ((pt (point)))
         (pp value)
         (save-excursion
@@ -689,7 +690,7 @@ SYMBOL is a function that can be overridden."
       )
      ((symbolp buffer-or-mode)
       (setq mode buffer-or-mode)
-      (princ (format "`%s'\n" buffer-or-mode))
+      (princ (format "‘%s’\n" buffer-or-mode))
       )
      ((signal 'wrong-type-argument
               (list 'buffer-or-mode buffer-or-mode))))
@@ -699,7 +700,7 @@ SYMBOL is a function that can be overridden."
     (while mode
       (setq table (get mode 'mode-local-symbol-table))
       (when table
-        (princ (format "\n- From `%s'\n" mode))
+        (princ (format "\n- From ‘%s’\n" mode))
         (mode-local-print-bindings table))
       (setq mode (get-mode-local-parent mode)))))
 
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index be75f37..b75a6609 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -253,7 +253,7 @@ that class.
  [ stuff ]  => @code{[ stuff ]}
  Key        => @kbd{Key}     (key is C\\-h, M\\-h, SPC, RET, TAB and the like)
  ...        => @dots{}"
-  (while (string-match "`\\([-a-zA-Z0-9<>.]+\\)'" string)
+  (while (string-match "[`‘]\\([-a-zA-Z0-9<>.]+\\)['’]" string)
     (let* ((vs (substring string (match-beginning 1) (match-end 1)))
 	   (v (intern-soft vs)))
       (setq string
diff --git a/lisp/cus-theme.el b/lisp/cus-theme.el
index 224d2c5..1321fbc 100644
--- a/lisp/cus-theme.el
+++ b/lisp/cus-theme.el
@@ -492,10 +492,10 @@ It includes all faces in list FACES."
 			 '("" "c")))
 	doc)
     (when fn
-      (princ " in `")
+      (princ " in ‘")
       (help-insert-xref-button (file-name-nondirectory fn)
 			       'help-theme-def fn)
-      (princ "'"))
+      (princ "’"))
     (princ ".\n")
     (if (custom-theme-p theme)
 	(progn
@@ -517,7 +517,7 @@ It includes all faces in list FACES."
 		 (setq doc (nth 2 sexp)))))))
     (princ "\n\nDocumentation:\n")
     (princ (if (stringp doc)
-	       doc
+	       (substitute-command-keys doc)
 	     "No documentation available.")))
   (princ "\n\nYou can ")
   (help-insert-xref-button "customize" 'help-theme-edit theme)
diff --git a/lisp/descr-text.el b/lisp/descr-text.el
index d6f64c7..fe48d46 100644
--- a/lisp/descr-text.el
+++ b/lisp/descr-text.el
@@ -161,8 +161,8 @@ otherwise."
       ;; Buttons
       (when (and button (not (widgetp wid-button)))
 	(newline)
-	(insert "Here is a `" (format "%S" button-type)
-		"' button labeled `" button-label "'.\n\n"))
+	(insert "Here is a ‘" (format "%S" button-type)
+		"’ button labeled ‘" button-label "’.\n\n"))
       ;; Overlays
       (when overlays
 	(newline)
@@ -731,7 +731,7 @@ relevant to POS."
                       (when face
                         (insert (propertize " " 'display '(space :align-to 5))
                                 "face: ")
-                        (insert (concat "`" (symbol-name face) "'"))
+                        (insert (concat "‘" (symbol-name face) "’"))
                         (insert "\n")))))
               (insert "these terminal codes:\n")
               (dotimes (i (length disp-vector))
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index fc257d0..903b4f2 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1524,7 +1524,7 @@ may require more formatting")
      ;;     Instead, use the `\\[...]' construct to stand for them.
      (save-excursion
        (let ((f nil) (m nil) (start (point))
-	     (re "[^`A-Za-z0-9_]\\([CMA]-[a-zA-Z]\\|\\(\\([CMA]-\\)?\
+	     (re "[^`‘A-Za-z0-9_]\\([CMA]-[a-zA-Z]\\|\\(\\([CMA]-\\)?\
 mouse-[0-3]\\)\\)\\>"))
 	 ;; Find the first key sequence not in a sample
 	 (while (and (not f) (setq m (re-search-forward re e t)))
@@ -1554,7 +1554,8 @@ mouse-[0-3]\\)\\)\\>"))
      (save-excursion
        (let ((case-fold-search t)
 	     (ret nil) mb me)
-	 (while (and (re-search-forward "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'" e t)
+	 (while (and (re-search-forward
+                      "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]" e t)
 		     (not ret))
 	   (let* ((ms1 (match-string 1))
 		  (sym (intern-soft ms1)))
@@ -1785,16 +1786,17 @@ Replace with \"%s\"? " original replace)
 	     )))
      ;;* When a documentation string refers to a Lisp symbol, write it as
      ;;  it would be printed (which usually means in lower case), with
-     ;;  single-quotes around it.  For example: `lambda'.  There are two
-     ;;  exceptions: write t and nil without single-quotes.  (In this
-     ;;  manual, we normally do use single-quotes for those symbols.)
+     ;;  single-quotes around it.  For example: ‘lambda’.  There are two
+     ;;  exceptions: write t and nil without single-quotes.  (For
+     ;;  compatibility with an older Emacs style, quoting with ` and '
+     ;;  also works, e.g., `lambda' is treated like ‘lambda’.)
      (save-excursion
        (let ((found nil) (start (point)) (msg nil) (ms nil))
 	 (while (and (not msg)
 		     (re-search-forward
 		      ;; Ignore manual page references like
 		      ;; git-config(1).
-		      "[^-([`':a-zA-Z]\\(\\w+[:-]\\(\\w\\|\\s_\\)+\\)[^](']"
+		      "[^-([`'‘’:a-zA-Z]\\(\\w+[:-]\\(\\w\\|\\s_\\)+\\)[^]('’]"
 		      e t))
 	   (setq ms (match-string 1))
 	   ;; A . is a \s_ char, so we must remove periods from
@@ -1812,7 +1814,7 @@ Replace with \"%s\"? " original replace)
 		 (if (checkdoc-autofix-ask-replace
 		      (match-beginning 1) (+ (match-beginning 1)
 					     (length ms))
-		      msg (concat "`" ms "'") t)
+		      msg (concat "‘" ms "’") t)
 		     (setq msg nil)
 		   (setq msg
 			 (format "Lisp symbol `%s' should appear in quotes"
@@ -1824,7 +1826,7 @@ Replace with \"%s\"? " original replace)
 	   nil)))
      ;; t and nil case
      (save-excursion
-       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
+       (if (re-search-forward "\\([`‘]\\(t\\|nil\\)['’]\\)" e t)
 	   (if (checkdoc-autofix-ask-replace
 		(match-beginning 1) (match-end 1)
 		(format "%s should not appear in quotes.  Remove? "
@@ -1989,7 +1991,7 @@ If the offending word is in a piece of quoted text, then it is skipped."
             (if (and (not (save-excursion
                             (goto-char b)
                             (forward-char -1)
-                            (looking-at "`\\|\"\\|\\.\\|\\\\")))
+                            (looking-at "[`\".‘]\\|\\\\")))
                      ;; surrounded by /, as in a URL or filename: /emacs/
                      (not (and (= ?/ (char-after e))
                                (= ?/ (char-before b))))
diff --git a/lisp/emacs-lisp/cl-generic.el b/lisp/emacs-lisp/cl-generic.el
index a2716ef..44f71db 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -865,11 +865,11 @@ Can only be used from within the lexical body of a primary or around method."
                                    (cl--generic-method-specializers method)))
                    (file (find-lisp-object-file-name met-name 'cl-defmethod)))
               (when file
-                (insert " in `")
+                (insert " in ‘")
                 (help-insert-xref-button (help-fns-short-filename file)
                                          'help-function-def met-name file
                                          'cl-defmethod)
-                (insert "'.\n")))
+                (insert "’.\n")))
             (insert "\n" (or (nth 2 info) "Undocumented") "\n\n")))))))
 
 ;;; Support for (head <val>) specializers.
diff --git a/lisp/emacs-lisp/eieio-opt.el b/lisp/emacs-lisp/eieio-opt.el
index 02b89e0..11d9984 100644
--- a/lisp/emacs-lisp/eieio-opt.el
+++ b/lisp/emacs-lisp/eieio-opt.el
@@ -90,11 +90,11 @@ If CLASS is actually an object, then also display current values of that object.
 	  " class")
   (let ((location (find-lisp-object-file-name class 'eieio-defclass)))
     (when location
-      (insert " in `")
+      (insert " in ‘")
       (help-insert-xref-button
        (help-fns-short-filename location)
        'eieio-class-def class location 'eieio-defclass)
-      (insert "'")))
+      (insert "’")))
   (insert ".\n")
   ;; Parents
   (let ((pl (eieio-class-parents class))
@@ -103,10 +103,10 @@ If CLASS is actually an object, then also display current values of that object.
       (insert " Inherits from ")
       (while (setq cur (pop pl))
 	(setq cur (eieio--class-name cur))
-	(insert "`")
+	(insert "‘")
 	(help-insert-xref-button (symbol-name cur)
 				 'help-function cur)
-	(insert (if pl "', " "'")))
+	(insert (if pl "’, " "’")))
       (insert ".\n")))
   ;; Children
   (let ((ch (eieio-class-children class))
@@ -114,10 +114,10 @@ If CLASS is actually an object, then also display current values of that object.
     (when ch
       (insert " Children ")
       (while (setq cur (pop ch))
-	(insert "`")
+	(insert "‘")
 	(help-insert-xref-button (symbol-name cur)
 				 'help-function cur)
-	(insert (if ch "', " "'")))
+	(insert (if ch "’, " "’")))
       (insert ".\n")))
   ;; System documentation
   (let ((doc (documentation-property class 'variable-documentation)))
@@ -130,9 +130,9 @@ If CLASS is actually an object, then also display current values of that object.
     (when generics
       (insert (propertize "Specialized Methods:\n\n" 'face 'bold))
       (dolist (generic generics)
-        (insert "`")
+        (insert "‘")
         (help-insert-xref-button (symbol-name generic) 'help-function generic)
-        (insert "'")
+        (insert "’")
 	(pcase-dolist (`(,qualifiers ,args ,doc)
                        (eieio-method-documentation generic class))
           (insert (format " %s%S\n" qualifiers args)
@@ -245,11 +245,11 @@ are not abstract."
 	(setq location
 	      (find-lisp-object-file-name ctr def)))
       (when location
-	(insert " in `")
+	(insert " in ‘")
 	(help-insert-xref-button
 	 (help-fns-short-filename location)
 	 'eieio-class-def ctr location 'eieio-defclass)
-	(insert "'"))
+	(insert "’"))
       (insert ".\nCreates an object of class " (symbol-name ctr) ".")
       (goto-char (point-max))
       (if (autoloadp def)
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 6facf57..ab01a10 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -403,8 +403,8 @@
          ;; Words inside \\[] tend to be for `substitute-command-keys'.
          ("\\\\\\\\\\[\\(\\(?:\\sw\\|\\s_\\)+\\)\\]"
           (1 font-lock-constant-face prepend))
-         ;; Words inside `' tend to be symbol names.
-         ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+         ;; Words inside ‘’ and `' tend to be symbol names.
+         ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
           (1 font-lock-constant-face prepend))
          ;; Constant values.
          ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
@@ -452,8 +452,8 @@
          ;; Erroneous structures.
          (,(concat "(" cl-errs-re "\\_>")
            (1 font-lock-warning-face))
-         ;; Words inside `' tend to be symbol names.
-         ("`\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)'"
+         ;; Words inside ‘’ and `' tend to be symbol names.
+         ("[`‘]\\(\\(?:\\sw\\|\\s_\\)\\(?:\\sw\\|\\s_\\)+\\)['’]"
           (1 font-lock-constant-face prepend))
          ;; Constant values.
          ("\\_<:\\(?:\\sw\\|\\s_\\)+\\_>" 0 font-lock-builtin-face)
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 1ab1b4b..8f06c81 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2160,17 +2160,17 @@ will be deleted."
                                    "Installed"
                                  (capitalize status)) ;FIXME: Why comment-face?
                                'font-lock-face 'font-lock-comment-face))
-           (insert " in `")
+           (insert " in ‘")
            ;; Todo: Add button for uninstalling.
            (help-insert-xref-button (abbreviate-file-name
                                      (file-name-as-directory pkg-dir))
                                     'help-package-def pkg-dir)
            (if (and (package-built-in-p name)
                     (not (package-built-in-p name version)))
-               (insert "',\n             shadowing a "
+               (insert "’,\n             shadowing a "
                        (propertize "built-in package"
                                    'font-lock-face 'font-lock-builtin-face))
-             (insert "'"))
+             (insert "’"))
            (if signed
                (insert ".")
              (insert " (unsigned)."))
diff --git a/lisp/faces.el b/lisp/faces.el
index 9c087c9..58a39f0 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -1428,18 +1428,19 @@ If FRAME is omitted or nil, use the selected frame."
 		  (when alias
 		    (setq face alias)
 		    (insert
-		     (format "\n  %s is an alias for the face `%s'.\n%s"
+		     (format "\n  %s is an alias for the face ‘%s’.\n%s"
 			     f alias
 			     (if (setq obsolete (get f 'obsolete-face))
-				 (format "  This face is obsolete%s; use `%s' instead.\n"
+				 (format "  This face is obsolete%s; use ‘%s’ instead.\n"
 					 (if (stringp obsolete)
 					     (format " since %s" obsolete)
 					   "")
 					 alias)
 			       ""))))
 		  (insert "\nDocumentation:\n"
-			  (or (face-documentation face)
-			      "Not documented as a face.")
+                          (substitute-command-keys
+                           (or (face-documentation face)
+                               "Not documented as a face."))
 			  "\n\n"))
 		(with-current-buffer standard-output
 		  (save-excursion
@@ -1448,12 +1449,12 @@ If FRAME is omitted or nil, use the selected frame."
 		    (help-xref-button 1 'help-customize-face f)))
 		(setq file-name (find-lisp-object-file-name f 'defface))
 		(when file-name
-		  (princ "Defined in `")
+		  (princ "Defined in ‘")
 		  (princ (file-name-nondirectory file-name))
-		  (princ "'")
+		  (princ "’")
 		  ;; Make a hyperlink to the library.
 		  (save-excursion
-		    (re-search-backward "`\\([^`']+\\)'" nil t)
+		    (re-search-backward "‘\\([^‘’]+\\)’" nil t)
 		    (help-xref-button 1 'help-face-def f file-name))
 		  (princ ".")
 		  (terpri)
diff --git a/lisp/finder.el b/lisp/finder.el
index 47fab3c..306f2e2 100644
--- a/lisp/finder.el
+++ b/lisp/finder.el
@@ -115,7 +115,7 @@ Each element has the form (KEYWORD . DESCRIPTION).")
   "Syntax table used while in `finder-mode'.")
 
 (defvar finder-font-lock-keywords
-  '(("`\\([^'`]+\\)'" 1 font-lock-constant-face prepend))
+  '(("[`‘]\\([^'`‘’]+\\)['’]" 1 font-lock-constant-face prepend))
   "Font-lock keywords for Finder mode.")
 
 (defvar finder-headmark nil
diff --git a/lisp/gnus/gnus-art.el b/lisp/gnus/gnus-art.el
index 7630afb..0ac9fb5 100644
--- a/lisp/gnus/gnus-art.el
+++ b/lisp/gnus/gnus-art.el
@@ -7827,11 +7827,11 @@ positives are possible."
     ("/\\([a-z][-a-z0-9]+\\.el\\)\\>[^.?]"
      ;; Exclude [.?] for URLs in gmane.emacs.cvs
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][-a-z0-9]+\\.el\\)'"
+    ("[`‘]\\([a-z][-a-z0-9]+\\.el\\)['’]"
      1 (>= gnus-button-emacs-level 8) gnus-button-handle-library 1)
-    ("`\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z0-9]+-[-a-z0-9]*[a-z]\\|\\(gnus\\|message\\)-[-a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 8) gnus-button-handle-symbol 1)
-    ("`\\([a-z][a-z0-9]+-[a-z]+\\)'"
+    ("[`‘]\\([a-z][a-z0-9]+-[a-z]+\\)['’]"
      0 (>= gnus-button-emacs-level 9) gnus-button-handle-symbol 1)
     ("(setq[ \t\n]+\\([a-z][a-z0-9]+-[-a-z0-9]+\\)[ \t\n]+.+)"
      1 (>= gnus-button-emacs-level 7) gnus-button-handle-describe-variable 1)
@@ -7841,7 +7841,7 @@ positives are possible."
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-function 2)
     ("\\b\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+v[ \t\n]+\\([^ \t\n]+\\)[ \t\n]+RET\\>"
      0 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-variable 2)
-    ("`\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^']+\\)\\)'"
+    ("[`‘]\\(\\(C-h\\|<?[Ff]1>?\\)[ \t\n]+k[ \t\n]+\\([^'’]+\\)\\)['’]"
      ;; Unlike the other regexps we really have to require quoting
      ;; here to determine where it ends.
      1 (>= gnus-button-emacs-level 1) gnus-button-handle-describe-key 3)
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 4982ee5..346e1e1 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -135,7 +135,7 @@ if the variable `help-downcase-arguments' is non-nil."
                          "\\)"
                          "\\(?:es\\|s\\|th\\)?"  ; for ARGth, ARGs
                          "\\(?:-[a-z0-9-]+\\)?"  ; for ARG-xxx, ARG-n
-                         "\\(?:-[{([<`\"].*?\\)?"; for ARG-{x}, (x), <x>, [x], `x'
+                         "\\(?:-[{([<`\"‘].*?\\)?"; for ARG-{x}, (x), <x>, [x], `x', ‘x’
                          "\\>")                  ; end of word
                  (help-highlight-arg arg)
                  doc t t 1)))
@@ -306,7 +306,7 @@ suitable file is found, return nil."
             (when remapped
               (princ "Its keys are remapped to ")
               (princ (if (symbolp remapped)
-			 (concat "`" (symbol-name remapped) "'")
+			 (concat "‘" (symbol-name remapped) "’")
 		       "an anonymous command"))
               (princ ".\n"))
 
@@ -340,16 +340,16 @@ suitable file is found, return nil."
       (insert "\nThis function has a compiler macro")
       (if (symbolp handler)
           (progn
-            (insert (format " `%s'" handler))
+            (insert (format " ‘%s’" handler))
             (save-excursion
-              (re-search-backward "`\\([^`']+\\)'" nil t)
+              (re-search-backward "‘\\([^‘’]+\\)’" nil t)
               (help-xref-button 1 'help-function handler)))
         ;; FIXME: Obsolete since 24.4.
         (let ((lib (get function 'compiler-macro-file)))
           (when (stringp lib)
-            (insert (format " in `%s'" lib))
+            (insert (format " in ‘%s’" lib))
             (save-excursion
-              (re-search-backward "`\\([^`']+\\)'" nil t)
+              (re-search-backward "‘\\([^‘’]+\\)’" nil t)
               (help-xref-button 1 'help-function-cmacro function lib)))))
       (insert ".\n"))))
 
@@ -393,13 +393,13 @@ suitable file is found, return nil."
                           (get function
                                'derived-mode-parent))))
     (when parent-mode
-      (insert "\nParent mode: `")
+      (insert "\nParent mode: ‘")
       (let ((beg (point)))
         (insert (format "%s" parent-mode))
         (make-text-button beg (point)
                           'type 'help-function
                           'help-args (list parent-mode)))
-      (insert "'.\n"))))
+      (insert "’.\n"))))
 
 (defun help-fns--obsolete (function)
   ;; Ignore lambda constructs, keyboard macros, etc.
@@ -415,7 +415,7 @@ suitable file is found, return nil."
       (when (nth 2 obsolete)
         (insert (format " since %s" (nth 2 obsolete))))
       (insert (cond ((stringp use) (concat ";\n" use))
-                    (use (format ";\nuse `%s' instead." use))
+                    (use (format ";\nuse ‘%s’ instead." use))
                     (t "."))
               "\n"))))
 
@@ -451,7 +451,7 @@ FILE is the file where FUNCTION was probably defined."
                           (format ";\nin Lisp code %s" interactive-only))
                          ((and (symbolp 'interactive-only)
                                (not (eq interactive-only t)))
-                          (format ";\nin Lisp code use `%s' instead."
+                          (format ";\nin Lisp code use ‘%s’ instead."
                                   interactive-only))
                          (t "."))
                    "\n")))))
@@ -520,7 +520,7 @@ FILE is the file where FUNCTION was probably defined."
 		 ;; Aliases are Lisp functions, so we need to check
 		 ;; aliases before functions.
 		 (aliased
-		  (format "an alias for `%s'" real-def))
+		  (format "an alias for ‘%s’" real-def))
 		 ((autoloadp def)
 		  (format "%s autoloaded %s"
 			  (if (commandp def) "an interactive" "an")
@@ -554,21 +554,21 @@ FILE is the file where FUNCTION was probably defined."
       (with-current-buffer standard-output
 	(save-excursion
 	  (save-match-data
-	    (when (re-search-backward "alias for `\\([^`']+\\)'" nil t)
+	    (when (re-search-backward "alias for ‘\\([^‘’]+\\)’" nil t)
 	      (help-xref-button 1 'help-function real-def)))))
 
       (when file-name
-	(princ " in `")
+	(princ " in ‘")
 	;; We used to add .el to the file name,
 	;; but that's completely wrong when the user used load-file.
 	(princ (if (eq file-name 'C-source)
 		   "C source code"
 		 (help-fns-short-filename file-name)))
-	(princ "'")
+	(princ "’")
 	;; Make a hyperlink to the library.
 	(with-current-buffer standard-output
 	  (save-excursion
-	    (re-search-backward "`\\([^`']+\\)'" nil t)
+	    (re-search-backward "‘\\([^‘’]+\\)’" nil t)
 	    (help-xref-button 1 'help-function-def function file-name))))
       (princ ".")
       (with-current-buffer (help-buffer)
@@ -702,14 +702,14 @@ it is displayed along with the global value."
 
 	      (if file-name
 		  (progn
-		    (princ " is a variable defined in `")
+		    (princ " is a variable defined in ‘")
 		    (princ (if (eq file-name 'C-source)
 			       "C source code"
 			     (file-name-nondirectory file-name)))
-		    (princ "'.\n")
+		    (princ "’.\n")
 		    (with-current-buffer standard-output
 		      (save-excursion
-			(re-search-backward "`\\([^`']+\\)'" nil t)
+			(re-search-backward "‘\\([^‘’]+\\)’" nil t)
 			(help-xref-button 1 'help-variable-def
 					  variable file-name)))
 		    (if valvoid
@@ -839,7 +839,8 @@ if it is given a local binding.\n")))
 	      ;; Mention if it's an alias.
               (unless (eq alias variable)
                 (setq extra-line t)
-                (princ (format "  This variable is an alias for `%s'.\n" alias)))
+                (princ (format "  This variable is an alias for ‘%s’.\n"
+                               alias)))
 
               (when obsolete
                 (setq extra-line t)
@@ -847,7 +848,8 @@ if it is given a local binding.\n")))
                 (if (nth 2 obsolete)
                     (princ (format " since %s" (nth 2 obsolete))))
 		(princ (cond ((stringp use) (concat ";\n  " use))
-			     (use (format ";\n  use `%s' instead." (car obsolete)))
+			     (use (format ";\n  use ‘%s’ instead."
+                                          (car obsolete)))
 			     (t ".")))
                 (terpri))
 
@@ -878,13 +880,13 @@ if it is given a local binding.\n")))
                               (setq file (car file)
                                     dir-file nil)))
 			(princ (if dir-file
-				   "by the file\n  `"
-				 "for the directory\n  `"))
+				   "by the file\n  ‘"
+				 "for the directory\n  ‘"))
 			(with-current-buffer standard-output
 			  (insert-text-button
 			   file 'type 'help-dir-local-var-def
 			   'help-args (list variable file)))
-			(princ "'.\n")))
+			(princ "’.\n")))
 		  (princ "  This variable's value is file-local.\n")))
 
 	      (when (memq variable ignored-local-variables)
@@ -899,7 +901,7 @@ variable.\n"))
 file-local variable.\n")
 		(when (assq variable safe-local-variable-values)
 		  (princ "  However, you have added it to \
-`safe-local-variable-values'.\n")))
+‘safe-local-variable-values’.\n")))
 
 	      (when safe-var
                 (setq extra-line t)
@@ -907,7 +909,7 @@ file-local variable.\n")
 		(princ "if its value\n  satisfies the predicate ")
 		(princ (if (byte-code-function-p safe-var)
 			   "which is a byte-compiled expression.\n"
-			 (format "`%s'.\n" safe-var))))
+			 (format "‘%s’.\n" safe-var))))
 
               (if extra-line (terpri))
 	      (princ "Documentation:\n")
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index f99e916..3fc0ad2 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -322,7 +322,7 @@ Commands:
 		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
 		    "[ \t\n]+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]"))
   "Regexp matching doc string references to symbols.
 
 The words preceding the quoted symbol can be used in doc strings to
@@ -337,11 +337,12 @@ when help commands related to multilingual environment (e.g.,
 
 
 (defconst help-xref-info-regexp
-  (purecopy "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+`\\([^']+\\)'")
+  (purecopy
+   "\\<[Ii]nfo[ \t\n]+\\(node\\|anchor\\)[ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to an Info node.")
 
 (defconst help-xref-url-regexp
-  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+`\\([^']+\\)'")
+  (purecopy "\\<[Uu][Rr][Ll][ \t\n]+[`‘]\\([^'’]+\\)['’]")
   "Regexp matching doc string references to a URL.")
 
 ;;;###autoload
diff --git a/lisp/help.el b/lisp/help.el
index 2b8f642..1411c1a 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -964,11 +964,12 @@ documentation for the major and minor modes of that buffer."
 	(let* ((mode major-mode)
 	       (file-name (find-lisp-object-file-name mode nil)))
 	  (when file-name
-	    (princ (concat " defined in `" (file-name-nondirectory file-name) "'"))
+	    (princ (concat " defined in ‘" (file-name-nondirectory file-name)
+                           "’"))
 	    ;; Make a hyperlink to the library.
 	    (with-current-buffer standard-output
 	      (save-excursion
-		(re-search-backward "`\\([^`']+\\)'" nil t)
+		(re-search-backward "‘\\([^‘’]+\\)’" nil t)
 		(help-xref-button 1 'help-function-def mode file-name)))))
 	(princ ":\n")
 	(princ (documentation major-mode)))))
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index 4b63cb8..c8cd76f 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -177,7 +177,7 @@
 		    "\\(charset\\)"
 		    "\\)\\s-+\\)?"
 		    ;; Note starting with word-syntax character:
-		    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'")))
+		    "[`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\)['’]")))
 
 (defun coding-system-change-eol-conversion (coding-system eol-type)
   "Return a coding system which differs from CODING-SYSTEM in EOL conversion.
@@ -1588,7 +1588,7 @@ which marks the variable `default-input-method' as set for Custom buffers."
 	 (with-output-to-temp-buffer (help-buffer)
 	   (let ((elt (assoc input-method input-method-alist)))
 	     (princ (format
-		     "Input method: %s (`%s' in mode line) for %s\n  %s\n"
+		     "Input method: %s (‘%s’ in mode line) for %s\n  %s\n"
 		     input-method (nth 3 elt) (nth 1 elt) (nth 4 elt))))))))))
 
 (defun describe-current-input-method ()
@@ -2173,10 +2173,11 @@ See `set-language-info-alist' for use in programs."
 	      (search-backward (symbol-name (car l)))
 	      (help-xref-button 0 'help-coding-system (car l))
 	      (goto-char (point-max))
-	      (insert " (`"
+	      (insert " (‘"
 		      (coding-system-mnemonic (car l))
-		      "' in mode line):\n\t"
-		      (coding-system-doc-string (car l))
+		      "’ in mode line):\n\t"
+                      (substitute-command-keys
+                       (coding-system-doc-string (car l)))
 		      "\n")
 	      (let ((aliases (coding-system-aliases (car l))))
 		(when aliases
diff --git a/lisp/international/mule-diag.el b/lisp/international/mule-diag.el
index 42e78f9..7ef758b 100644
--- a/lisp/international/mule-diag.el
+++ b/lisp/international/mule-diag.el
@@ -332,7 +332,7 @@ meanings of these arguments."
       (let ((char (charset-iso-final-char charset)))
 	(when (> char 0)
 	  (insert "Final char of ISO2022 designation sequence: ")
-	  (insert (format "`%c'\n" char))))
+	  (insert (format "‘%c’\n" char))))
       (let (aliases)
 	(dolist (c charset-list)
 	  (if (and (not (eq c charset))
@@ -581,7 +581,7 @@ docstring, and print only the first line of the docstring."
 	    (if (string-match "\n" doc)
 		(setq doc (substring doc 0 (match-beginning 0))))
 	    (setq doc (concat "  " doc)))
-	  (princ (format "%s\n" doc))))))
+	  (princ (format "%s\n" (substitute-command-keys doc)))))))
 
 ;;;###autoload
 (defun describe-current-coding-system ()
@@ -1038,7 +1038,7 @@ see the function `describe-fontset' for the format of the list."
       (save-excursion
 	(goto-char (point-min))
 	(while (re-search-forward
-		"^  \\([^ ]+\\) (`.*' in mode line)$" nil t)
+		"^  \\([^ ]+\\) (‘.*’ in mode line)$" nil t)
 	  (help-xref-button 1 'help-input-method (match-string 1)))))))
 
 (defun list-input-methods-1 ()
@@ -1046,7 +1046,7 @@ see the function `describe-fontset' for the format of the list."
       (princ "
 No input method is available, perhaps because you have not
 installed LEIM (Libraries of Emacs Input Methods).")
-    (princ "LANGUAGE\n  NAME (`TITLE' in mode line)\n")
+    (princ "LANGUAGE\n  NAME (‘TITLE’ in mode line)\n")
     (princ "    SHORT-DESCRIPTION\n------------------------------\n")
     (setq input-method-alist
 	  (sort input-method-alist
@@ -1058,7 +1058,7 @@ installed LEIM (Libraries of Emacs Input Methods).")
 	  (setq language (nth 1 elt))
 	  (princ language)
 	  (terpri))
-	(princ (format "  %s (`%s' in mode line)\n    %s\n"
+	(princ (format "  %s (‘%s’ in mode line)\n    %s\n"
 		       (car elt)
 		       (let ((title (nth 3 elt)))
 			 (if (and (consp title) (stringp (car title)))
@@ -1066,8 +1066,9 @@ installed LEIM (Libraries of Emacs Input Methods).")
 			   title))
 		       ;; If the doc is multi-line, indent all
 		       ;; non-blank lines. (Bug#8066)
-		       (replace-regexp-in-string "\n\\(.\\)" "\n    \\1"
-						 (or (nth 4 elt) ""))))))))
+		       (replace-regexp-in-string
+                        "\n\\(.\\)" "\n    \\1"
+                        (substitute-command-keys (or (nth 4 elt) "")))))))))
 \f
 ;;; DIAGNOSIS
 
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index e06b920..b070029 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -231,7 +231,7 @@ Blank lines separate paragraphs.  Semicolons start comments.
   (lisp-mode-variables nil nil 'elisp)
   (add-hook 'after-load-functions #'elisp--font-lock-flush-elisp-buffers)
   (setq-local electric-pair-text-pairs
-              (cons '(?\` . ?\') electric-pair-text-pairs))
+              (append '((?\` . ?\') (?‘ . ?’)) electric-pair-text-pairs))
   (setq imenu-case-fold-search nil)
   (add-function :before-until (local 'eldoc-documentation-function)
                 #'elisp-eldoc-documentation-function)
@@ -394,7 +394,7 @@ It can be quoted, or be inside a quoted form."
                ((or (eq (char-after) ?\[)
                     (progn
                       (skip-chars-backward " ")
-                      (memq (char-before) '(?' ?`))))
+                      (memq (char-before) '(?' ?` ?‘))))
                 (setq res t))
                ((eq (char-before) ?,)
                 (setq nesting nil))))
@@ -459,7 +459,7 @@ It can be quoted, or be inside a quoted form."
 	   (beg (condition-case nil
 		    (save-excursion
 		      (backward-sexp 1)
-		      (skip-syntax-forward "'")
+		      (skip-chars-forward "`',‘")
 		      (point))
 		  (scan-error pos)))
 	   (end
@@ -470,7 +470,7 @@ It can be quoted, or be inside a quoted form."
 		  (save-excursion
 		    (goto-char beg)
 		    (forward-sexp 1)
-                    (skip-chars-backward "'")
+                    (skip-chars-backward "'’")
 		    (when (>= (point) pos)
 		      (point)))
 		(scan-error pos))))
@@ -478,7 +478,7 @@ It can be quoted, or be inside a quoted form."
            (funpos (eq (char-before beg) ?\())
            (quoted (elisp--form-quoted-p beg)))
       (when (and end (or (not (nth 8 (syntax-ppss)))
-                         (eq (char-before beg) ?`)))
+                         (memq (char-before beg) '(?` ?‘))))
         (let ((table-etc
                (if (or (not funpos) quoted)
                    ;; FIXME: We could look at the first element of the list and
@@ -901,15 +901,17 @@ If CHAR is not a character, return nil."
 (defun elisp--preceding-sexp ()
   "Return sexp before the point."
   (let ((opoint (point))
-	ignore-quotes
+	(left-quote ?‘)
 	expr)
     (save-excursion
       (with-syntax-table emacs-lisp-mode-syntax-table
-	;; If this sexp appears to be enclosed in `...'
+	;; If this sexp appears to be enclosed in `...' or ‘...’
 	;; then ignore the surrounding quotes.
-	(setq ignore-quotes
-	      (or (eq (following-char) ?\')
-		  (eq (preceding-char) ?\')))
+	(cond ((eq (preceding-char) ?’)
+	       (progn (forward-char -1) (setq opoint (point))))
+	      ((or (eq (following-char) ?\')
+		   (eq (preceding-char) ?\'))
+	       (setq left-quote ?\`)))
 	(forward-sexp -1)
 	;; If we were after `?\e' (or similar case),
 	;; use the whole thing, not just the `e'.
@@ -933,7 +935,7 @@ If CHAR is not a character, return nil."
 	      (forward-sexp -1))))
 
 	(save-restriction
-	  (if (and ignore-quotes (eq (following-char) ?`))
+	  (if (eq (following-char) left-quote)
               ;; vladimir@cs.ualberta.ca 30-Jul-1997: Skip ` in `variable' so
               ;; that the value is returned, not the name.
 	      (forward-char))
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 0a95783..dac3b1e 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2863,7 +2863,7 @@ The following properties have special meanings for this widget:
   :type 'boolean
   :group 'widget-documentation)
 
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "[`‘]\\([^\n `'‘’]+\\)['’]"
   "Regexp for matching potential links in documentation strings.
 The first group should be the link itself."
   :type 'regexp
-- 
2.1.0


[-- Attachment #4: 0003-Fix-minor-quoting-problems-in-doc-strings.txt --]
[-- Type: text/plain, Size: 57529 bytes --]

From 65127c3af36034e1efd74251603b6256cdc1b5ef Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 20 May 2015 23:55:41 -0700
Subject: [PATCH 3/3] Fix minor quoting problems in doc strings

Most of these fixes involve escaping grave accents that are
actually intended to be grave accents, not left quotes.
(Bug#20385)
---
 etc/edt-user.el                      |   2 +-
 lisp/calc/calc-misc.el               |   4 +-
 lisp/cedet/semantic/wisent/wisent.el |   8 +-
 lisp/cedet/srecode/texi.el           |   2 +-
 lisp/emacs-lisp/macroexp.el          |   2 +-
 lisp/emulation/viper-cmd.el          |   2 +-
 lisp/erc/erc.el                      |   2 +-
 lisp/eshell/em-dirs.el               |   2 +-
 lisp/files.el                        |   2 +-
 lisp/gnus/smime.el                   |   2 +-
 lisp/ido.el                          |   4 +-
 lisp/language/ethio-util.el          |   6 +-
 lisp/leim/quail/cyrillic.el          |   4 +-
 lisp/leim/quail/greek.el             |   2 +-
 lisp/leim/quail/hebrew.el            |   6 +-
 lisp/leim/quail/latin-alt.el         | 150 +++++++++++++++++------------------
 lisp/leim/quail/latin-post.el        |  26 +++---
 lisp/leim/quail/latin-pre.el         |  24 +++---
 lisp/leim/quail/thai.el              |   2 +-
 lisp/leim/quail/tibetan.el           |   2 +-
 lisp/leim/quail/viqr.el              |   2 +-
 lisp/obsolete/iso-acc.el             |   4 +-
 lisp/obsolete/scribe.el              |   8 +-
 lisp/obsolete/sregex.el              |   2 +-
 lisp/obsolete/tpu-edt.el             |   2 +-
 lisp/obsolete/tpu-mapper.el          |   2 +-
 lisp/org/ob-core.el                  |   2 +-
 lisp/org/org-agenda.el               |   2 +-
 lisp/progmodes/cperl-mode.el         |   8 +-
 lisp/progmodes/f90.el                |   4 +-
 lisp/progmodes/idlwave.el            |   4 +-
 lisp/progmodes/sh-script.el          |   2 +-
 lisp/progmodes/verilog-mode.el       |  76 +++++++++---------
 lisp/skeleton.el                     |   2 +-
 lisp/textmodes/tex-mode.el           |   8 +-
 lisp/textmodes/texinfmt.el           |   6 +-
 lisp/textmodes/texinfo.el            |   2 +-
 37 files changed, 195 insertions(+), 195 deletions(-)

diff --git a/etc/edt-user.el b/etc/edt-user.el
index e0f5b29..2666856 100644
--- a/etc/edt-user.el
+++ b/etc/edt-user.el
@@ -160,7 +160,7 @@ G-C-\\: Split Window
   G-%: Go to Percentage
   G- : Undo  (GOLD Spacebar)
   G-=: Go to Line
-  G-`: What line
+  G-\\=`: What line
   G-/: Query-Replace"
 
   (interactive)
diff --git a/lisp/calc/calc-misc.el b/lisp/calc/calc-misc.el
index 9c5d718..60c6fb9 100644
--- a/lisp/calc/calc-misc.el
+++ b/lisp/calc/calc-misc.el
@@ -89,7 +89,7 @@ For use with Embedded mode:
   N  calc-embedded-next.  Advance cursor to next known formula in buffer.
   P  calc-embedded-previous.  Advance cursor to previous known formula.
   U  calc-embedded-update-formula.  Re-evaluate formula at point.
-  `  calc-embedded-edit.  Use calc-edit to edit formula at point.
+  \\=`  calc-embedded-edit.  Use calc-edit to edit formula at point.
 
 Documentation:
   I  calc-info.  Read the Calculator manual in the Emacs Info system.
@@ -225,7 +225,7 @@ Calc user interface as before (either C-x * C or C-x * K; initially C-x * C).
 	   "Letter keys: SHIFT + Num-eval; More-recn; eXec-kbd-macro; Keep-args"
 	   "Other keys: +, -, *, /, ^, \\ (int div), : (frac div)"
 	   "Other keys: & (1/x), | (concat), % (modulo), ! (factorial)"
-	   "Other keys: ' (alg-entry), = (eval), ` (edit); M-RET (last-args)"
+	   "Other keys: ' (alg-entry), = (eval), \\=` (edit); M-RET (last-args)"
 	   "Other keys: SPC/RET (enter/dup), LFD (over); < > (scroll horiz)"
 	   "Other keys: DEL (drop), M-DEL (drop-above); { } (scroll vert)"
 	   "Other keys: TAB (swap/roll-dn), M-TAB (roll-up)"
diff --git a/lisp/cedet/semantic/wisent/wisent.el b/lisp/cedet/semantic/wisent/wisent.el
index fd00080..fb77cb3 100644
--- a/lisp/cedet/semantic/wisent/wisent.el
+++ b/lisp/cedet/semantic/wisent/wisent.el
@@ -44,11 +44,11 @@
   "
            /\\_.-^^^-._/\\     The GNU
            \\_         _/
-            (     `o  `      (European ;-) Bison
-             \\      ` /
+            (     \\=`o  \\=`      (European ;-) Bison
+             \\      \\=` /
              (   D  ,\"       for Emacs!
-              ` ~ ,\"
-               `\"\""
+              \\=` ~ ,\"
+               \\=`\"\""
   :group 'semantic)
 
 \f
diff --git a/lisp/cedet/srecode/texi.el b/lisp/cedet/srecode/texi.el
index b75a6609..6c8f7a6 100644
--- a/lisp/cedet/srecode/texi.el
+++ b/lisp/cedet/srecode/texi.el
@@ -245,7 +245,7 @@ that class.
  variable   => @code{variable}
  class      => @code{class} @xref{class}
  unknown    => @code{unknown}
- \" text \"   => `` text ''
+ \"text\"     => \\=`\\=`text''
  'quoteme   => @code{quoteme}
  non-nil    => non-@code{nil}
  t          => @code{t}
diff --git a/lisp/emacs-lisp/macroexp.el b/lisp/emacs-lisp/macroexp.el
index f0410f8..05ffa8d 100644
--- a/lisp/emacs-lisp/macroexp.el
+++ b/lisp/emacs-lisp/macroexp.el
@@ -343,7 +343,7 @@ definitions to shadow the loaded ones for use in file byte-compilation."
 
 (defmacro macroexp-let2 (test var exp &rest exps)
   "Bind VAR to a copyable expression that returns the value of EXP.
-This is like `(let ((v ,EXP)) ,EXPS) except that `v' is a new generated
+This is like \\=`(let ((v ,EXP)) ,EXPS) except that `v' is a new generated
 symbol which EXPS can find in VAR.
 TEST should be the name of a predicate on EXP checking whether the `let' can
 be skipped; if nil, as is usual, `macroexp-const-p' is used."
diff --git a/lisp/emulation/viper-cmd.el b/lisp/emulation/viper-cmd.el
index 5c91df9..5e1620d 100644
--- a/lisp/emulation/viper-cmd.el
+++ b/lisp/emulation/viper-cmd.el
@@ -4400,7 +4400,7 @@ and regexp replace."
 ;; etc.
 (defun viper-cycle-through-mark-ring ()
   "Visit previous locations on the mark ring.
-One can use `` and '' to temporarily jump 1 step back."
+One can use \\=`\\=` and '' to temporarily jump 1 step back."
   (let* ((sv-pt (point)))
        ;; if repeated `m,' command, pop the previously saved mark.
        ;; Prev saved mark is actually prev saved point.  It is used if the
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index cf422f1..4537745 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -2460,7 +2460,7 @@ on the given server.")
 (defcustom erc-lurker-trim-nicks t
   "If t, trim trailing `erc-lurker-ignore-chars' from nicks.
 
-This causes e.g. nick and nick` to be considered as the same
+This causes e.g. nick and nick\\=` to be considered as the same
 individual for activity tracking and lurkiness detection
 purposes."
   :group 'erc-lurker
diff --git a/lisp/eshell/em-dirs.el b/lisp/eshell/em-dirs.el
index 84d46dc..980a340 100644
--- a/lisp/eshell/em-dirs.el
+++ b/lisp/eshell/em-dirs.el
@@ -300,7 +300,7 @@ Thus, this does not include the current directory.")
 		 eshell-user-names)))))))
 
 (defun eshell/pwd (&rest args)
-  "Change output from `pwd` to be cleaner."
+  "Change output from \\=`pwd\\=` to be cleaner."
   (let* ((path default-directory)
 	 (len (length path)))
     (if (and (> len 1)
diff --git a/lisp/files.el b/lisp/files.el
index ef6ac7b..e54a2be 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -55,7 +55,7 @@ FROM with TO when it appears in a directory name.  This replacement is
 done when setting up the default directory of a newly visited file.
 
 FROM is matched against directory names anchored at the first
-character, so it should start with a \"\\\\`\", or, if directory
+character, so it should start with a \"\\\\\\=`\", or, if directory
 names cannot have embedded newlines, with a \"^\".
 
 FROM and TO should be equivalent names, which refer to the
diff --git a/lisp/gnus/smime.el b/lisp/gnus/smime.el
index 6f043df..76d58f7 100644
--- a/lisp/gnus/smime.el
+++ b/lisp/gnus/smime.el
@@ -158,7 +158,7 @@ certificates to be sent with every message to each address."
 Directory should contain files (in PEM format) named to the X.509
 hash of the certificate.  This can be done using OpenSSL such as:
 
-$ ln -s ca.pem `openssl x509 -noout -hash -in ca.pem`.0
+$ ln -s ca.pem \\=`openssl x509 -noout -hash -in ca.pem\\=`.0
 
 where `ca.pem' is the file containing a PEM encoded X.509 CA
 certificate."
diff --git a/lisp/ido.el b/lisp/ido.el
index b97f72c..5995fcd 100644
--- a/lisp/ido.el
+++ b/lisp/ido.el
@@ -377,7 +377,7 @@ use either \\[customize] or the function `ido-mode'."
   '("\\` ")
   "List of regexps or functions matching buffer names to ignore.
 For example, traditional behavior is not to list buffers whose names begin
-with a space, for which the regexp is ‘\\` ’.  See the source file for
+with a space, for which the regexp is ‘\\\\=` ’.  See the source file for
 example functions that filter buffer names."
   :type '(repeat (choice regexp function))
   :group 'ido)
@@ -386,7 +386,7 @@ example functions that filter buffer names."
   '("\\`CVS/" "\\`#" "\\`.#" "\\`\\.\\./" "\\`\\./")
   "List of regexps or functions matching file names to ignore.
 For example, traditional behavior is not to list files whose names begin
-with a #, for which the regexp is ‘\\`#’.  See the source file for
+with a #, for which the regexp is ‘\\\\=`#’.  See the source file for
 example functions that filter filenames."
   :type '(repeat (choice regexp function))
   :group 'ido)
diff --git a/lisp/language/ethio-util.el b/lisp/language/ethio-util.el
index a27f749..1278657 100644
--- a/lisp/language/ethio-util.el
+++ b/lisp/language/ethio-util.el
@@ -129,9 +129,9 @@ isolated vowel.")
   "Degree of reduction in converting Ethiopic digits into Arabic digits.
 Should be 0, 1 or 2.
 For example, ({10}{9}{100}{80}{7}) is converted into:
-    `10`9`100`80`7  if `ethio-numeric-reduction' is 0,
-    `109100807	    if `ethio-numeric-reduction' is 1,
-    `10900807	    if `ethio-numeric-reduction' is 2.")
+    \\=`10\\=`9\\=`100\\=`80\\=`7  if `ethio-numeric-reduction' is 0,
+    \\=`109100807	    if `ethio-numeric-reduction' is 1,
+    \\=`10900807	    if `ethio-numeric-reduction' is 2.")
 
 (defvar ethio-java-save-lowercase nil
   "Non-nil means save Ethiopic characters in lowercase hex numbers to Java files.
diff --git a/lisp/leim/quail/cyrillic.el b/lisp/leim/quail/cyrillic.el
index 7caa5ec..ecee243 100644
--- a/lisp/leim/quail/cyrillic.el
+++ b/lisp/leim/quail/cyrillic.el
@@ -1245,7 +1245,7 @@ This phonetic layout replaces all the Latin letters with Bulgarian
 \(Cyrillic) letters based on similarities in their pronunciation or look.
 
 Note that, since the letters ‘щ’, ‘ь’, ‘ю’ and ‘я’ are attached to the
-‘]’, ‘\’, ‘`’ and ‘[’ keys respectively, Caps Lock does not affect them."
+‘]’, ‘\’, ‘\\=`’ and ‘[’ keys respectively, Caps Lock does not affect them."
 nil t t t t nil nil nil nil nil t)
 
 ;;  Ю  1! 2@ 3№ 4$ 5% 6€ 7§ 8* 9( 0) -– =+ ьѝ
@@ -1412,7 +1412,7 @@ The letters Ц, М, Ч, Р, Л, Б and Ы are not affected by Caps Lock.
 In addition to original Bulgarian typewriter layout, keys \\ and |
 are transformed into ' and Ы respectively.  Some keyboards mark these
 keys as being transformed into ( and ) respectively.  For ( and ), use
-` and ~ respectively.  This input method follows XKB."
+\\=` and ~ respectively.  This input method follows XKB."
  nil t t t t nil nil nil nil nil t)
 
 ;;  () 1! 2? 3+ 4" 5% 6= 7: 8/ 9_ 0№ -I .V
diff --git a/lisp/leim/quail/greek.el b/lisp/leim/quail/greek.el
index 5c5ead7..cf99150 100644
--- a/lisp/leim/quail/greek.el
+++ b/lisp/leim/quail/greek.el
@@ -179,7 +179,7 @@ mark		key
 ------------------------
 ypogegrammeni	J
 psili		'  or  v
-dasia		`  or  V
+dasia		\\=`  or  V
 oxia		/
 varia		?
 perispomeni	\\  or  ^
diff --git a/lisp/leim/quail/hebrew.el b/lisp/leim/quail/hebrew.el
index 5d63e40..1601e1e 100644
--- a/lisp/leim/quail/hebrew.el
+++ b/lisp/leim/quail/hebrew.el
@@ -113,8 +113,8 @@ Only Hebrew-related characters are considered.
 
 Based on latest draft of SI-1452 keyboard layout.
 Only Hebrew-related characters are considered.
- ‘`’ is used to switch levels instead of Alt-Gr.
-Geresh is mapped to ‘`k’.
+ ‘\\=`’ is used to switch levels instead of Alt-Gr.
+Geresh is mapped to ‘\\=`k’.
 " nil t t t t nil nil nil nil nil t)
 
 (quail-define-rules
@@ -603,7 +603,7 @@ Not suitable for modern Hebrew input.
 
 Based on Society of Biblical Literature's SIL keyboard layout.
 Phonetic and not suitable for modern Hebrew input.
- ‘`’ is used to switch levels instead of Alt-Gr.
+ ‘\\=`’ is used to switch levels instead of Alt-Gr.
  Euro Sign (€) is mapped to ‘Z’.
 " nil t t t t nil nil nil nil nil t)
 
diff --git a/lisp/leim/quail/latin-alt.el b/lisp/leim/quail/latin-alt.el
index 4c886fa..0614ecb 100644
--- a/lisp/leim/quail/latin-alt.el
+++ b/lisp/leim/quail/latin-alt.el
@@ -49,7 +49,7 @@ special (so you can use that to enter a slash).
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
@@ -209,20 +209,20 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "latin-2-alt-postfix" "Latin-2" "2<" t
  "Latin-2 character input method with postfix modifiers
 This input method differs from `latin-2-postfix' in that
-comma and period are not special (use ` instead).
+comma and period are not special (use \\=` instead).
 
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  ogonek     |    `    | a` -> ą
+  ogonek     |    \\=`    | a\\=` -> ą
   diaeresis  |    \"    | a\" -> ä
   circumflex |    ^    | a^ -> â
   breve      |    ~    | a~ -> ă
-  cedilla    |    `    | c` -> ç
+  cedilla    |    \\=`    | c\\=` -> ç
   caron      |    ~    | c~ -> č
   dbl. acute |    :    | o: -> ő
-  ring       |    `    | u` -> ů
-  dot        |    `    | z` -> ż
+  ring       |    \\=`    | u\\=` -> ů
+  dot        |    \\=`    | z\\=` -> ż
   stroke     |    /    | d/ -> đ
   others     |    /    | s/ -> ß
 
@@ -403,17 +403,17 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "latin-3-alt-postfix" "Latin-3" "3<" t
  "Latin-3 character input method with postfix modifiers
 This input method differs from `latin-3-postfix' in that
-comma is not special (use ` instead), and period is not
+comma is not special (use \\=` instead), and period is not
 special (use slash instead).
 
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   dot        |    /    | c/ -> ċ   i/ -> ı   I/ -> İ
-  cedilla    |    `    | c` -> ç
+  cedilla    |    \\=`    | c\\=` -> ç
   breve      |    ~    | g~ -> ğ
   tilde      |    ~    | n~ -> ñ
   stroke     |    /    | h/ -> ħ
@@ -576,7 +576,7 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "latin-4-alt-postfix" "Latin-4" "4<" t
  "Latin-4 characters input method with postfix modifiers
 This input method differs from `latin-4-postfix' in that
-comma is not special (use ` instead), and period is not
+comma is not special (use \\=` instead), and period is not
 special (use ~ instead).
 
              | postfix | examples
@@ -584,12 +584,12 @@ special (use ~ instead).
   acute      |    '    | a' -> á
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
-  ogonek     |    `    | a` -> ą
+  ogonek     |    \\=`    | a\\=` -> ą
   macron     |    -    | a- -> ā
   tilde      |    ~    | a~ -> ã
   caron      |    ~    | c~ -> č
   dot        |    ~    | e~ -> ė
-  cedilla    |    `    | k` -> ķ   g` -> ģ
+  cedilla    |    \\=`    | k\\=` -> ķ   g\\=` -> ģ
   stroke     |    /    | d/ -> đ
   nordic     |    /    | a/ -> å   e/ -> æ   o/ -> ø
   others     |    /    | s/ -> ß   n/ -> ŋ   k/ -> ĸ
@@ -773,18 +773,18 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "latin-5-alt-postfix" "Latin-5" "5<" t
  "Latin-5 characters input method with postfix modifiers
 This input method differs from `latin-5-postfix' in that
-comma is not special (use ` instead), and period is not
+comma is not special (use \\=` instead), and period is not
 special (use / instead).
 
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
   breve      |    ~    | g~ -> ğ
-  cedilla    |    `    | c` -> ç
+  cedilla    |    \\=`    | c\\=` -> ç
   dot        |    /    | i/ -> ı   I/ -> İ
   nordic     |    /    | a/ -> å   e/ -> æ   o/ -> ø
   others     |    /    | s/ -> ß
@@ -930,8 +930,8 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "french-alt-postfix" "French" "FR<" t
  "French (Français) input method with postfix modifiers
 
-` pour grave, ' pour aigu, ^ pour circonflexe, et \" pour tréma.
-Par exemple: a` -> à   e' -> é.
+\\=` pour grave, ' pour aigu, ^ pour circonflexe, et \" pour tréma.
+Par exemple: a\\=` -> à   e' -> é.
 
 Ç, «, et » sont produits par C/, <<, et >>.
 
@@ -1011,15 +1011,15 @@ Par exemple: e'' -> e'
  "italian-alt-postfix" "Latin-1" "IT<" t
  "Italian (Italiano) input method with postfix modifiers
 
-a' -> á    A' -> Á    a` -> à    A` -> À    i^ -> î    << -> «
-e' -> é    E' -> É    e` -> è    E` -> È    I^ -> Î    >> -> »
-i' -> í    I' -> Í    i` -> ì    I` -> Ì               o_ -> º
-o' -> ó    O' -> Ó    o` -> ò    O` -> Ò               a_ -> ª
-u' -> ú    U' -> Ú    u` -> ù    U` -> Ù
+a' -> á    A' -> Á    a\\=` -> à    A\\=` -> À    i^ -> î    << -> «
+e' -> é    E' -> É    e\\=` -> è    E\\=` -> È    I^ -> Î    >> -> »
+i' -> í    I' -> Í    i\\=` -> ì    I\\=` -> Ì               o_ -> º
+o' -> ó    O' -> Ó    o\\=` -> ò    O\\=` -> Ò               a_ -> ª
+u' -> ú    U' -> Ú    u\\=` -> ù    U\\=` -> Ù
 
 This method is for purists who like accents the old way.
 
-Doubling the postfix separates the letter and postfix: e.g. a`` -> a`
+Doubling the postfix separates the letter and postfix: e.g. a\\=`\\=` -> a\\=`
 " nil t nil nil nil nil nil nil nil nil t)
 
 (quail-define-rules
@@ -1083,21 +1083,21 @@ Doubling the postfix separates the letter and postfix: e.g. a`` -> a`
  "turkish-alt-postfix" "Turkish" "TR«" t
  "Turkish (Türkçe) input method with postfix modifiers.
 This input method differs from `turkish-postfix' in that
-comma is not special (use ` instead).
+comma is not special (use \\=` instead).
 
 turkish-latin-3-alt-postfix is an obsolete alias for turkish-alt-postfix.
 
 Note for I, ı, İ, i.
 
 A^ -> Â
-C` -> Ç
+C\\=` -> Ç
 G^ -> Ğ
 I  -> I
 i  -> ı
 I/ -> İ
 i/ -> i
 O\" -> Ö
-S` -> Ş
+S\\=` -> Ş
 U\" -> Ü
 U^ -> Û
 
@@ -1161,7 +1161,7 @@ Caters for French and Turkish as well as Dutch.
              | postfix |
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   Turkish    | various | i/ -> ı  s, -> ş  g^ -> ğ   I/ -> İ
              |         |  S, -> Ş  G^ -> Ğ
@@ -1180,61 +1180,61 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  ("ij" ?ij) ;; LATIN SMALL LIGATURE IJ
  ("IJ" ?IJ) ;; LATIN CAPITAL LIGATURE IJ
  ;; “Trema on the second letter of vowel pair.”  Yudit uses `:', not `"'.
- ("\"a" ?ä) ;; LATIN SMALL LETTER A WITH DIAERESIS 
- ("\"e" ?ë) ;; LATIN SMALL LETTER E WITH DIAERESIS 
- ("\"i" ?ï) ;; LATIN SMALL LETTER I WITH DIAERESIS 
- ("\"o" ?ö) ;; LATIN SMALL LETTER O WITH DIAERESIS 
- ("\"u" ?ü) ;; LATIN SMALL LETTER U WITH DIAERESIS 
- ("\"A" ?Ä) ;; LATIN CAPITAL LETTER A WITH DIAERESIS 
- ("\"E" ?Ë) ;; LATIN CAPITAL LETTER E WITH DIAERESIS 
- ("\"I" ?Ï) ;; LATIN CAPITAL LETTER I WITH DIAERESIS 
- ("\"O" ?Ö) ;; LATIN CAPITAL LETTER O WITH DIAERESIS 
- ("\"U" ?Ü) ;; LATIN CAPITAL LETTER U WITH DIAERESIS 
+ ("\"a" ?ä) ;; LATIN SMALL LETTER A WITH DIAERESIS
+ ("\"e" ?ë) ;; LATIN SMALL LETTER E WITH DIAERESIS
+ ("\"i" ?ï) ;; LATIN SMALL LETTER I WITH DIAERESIS
+ ("\"o" ?ö) ;; LATIN SMALL LETTER O WITH DIAERESIS
+ ("\"u" ?ü) ;; LATIN SMALL LETTER U WITH DIAERESIS
+ ("\"A" ?Ä) ;; LATIN CAPITAL LETTER A WITH DIAERESIS
+ ("\"E" ?Ë) ;; LATIN CAPITAL LETTER E WITH DIAERESIS
+ ("\"I" ?Ï) ;; LATIN CAPITAL LETTER I WITH DIAERESIS
+ ("\"O" ?Ö) ;; LATIN CAPITAL LETTER O WITH DIAERESIS
+ ("\"U" ?Ü) ;; LATIN CAPITAL LETTER U WITH DIAERESIS
  ;; “Acute, marking emphasis on long vowels”:
- ("a'" ?á) ;; LATIN SMALL LETTER A WITH ACUTE 
- ("e'" ?é) ;; LATIN SMALL LETTER E WITH ACUTE 
- ("i'" ?í) ;; LATIN SMALL LETTER I WITH ACUTE 
- ("o'" ?ó) ;; LATIN SMALL LETTER O WITH ACUTE 
- ("u'" ?ú) ;; LATIN SMALL LETTER U WITH ACUTE 
- ("A'" ?Á) ;; LATIN CAPITAL LETTER A WITH ACUTE 
- ("E'" ?É) ;; LATIN CAPITAL LETTER E WITH ACUTE 
- ("I'" ?Í) ;; LATIN CAPITAL LETTER I WITH ACUTE 
- ("O'" ?Ó) ;; LATIN CAPITAL LETTER O WITH ACUTE 
- ("U'" ?Ú) ;; LATIN CAPITAL LETTER U WITH ACUTE 
+ ("a'" ?á) ;; LATIN SMALL LETTER A WITH ACUTE
+ ("e'" ?é) ;; LATIN SMALL LETTER E WITH ACUTE
+ ("i'" ?í) ;; LATIN SMALL LETTER I WITH ACUTE
+ ("o'" ?ó) ;; LATIN SMALL LETTER O WITH ACUTE
+ ("u'" ?ú) ;; LATIN SMALL LETTER U WITH ACUTE
+ ("A'" ?Á) ;; LATIN CAPITAL LETTER A WITH ACUTE
+ ("E'" ?É) ;; LATIN CAPITAL LETTER E WITH ACUTE
+ ("I'" ?Í) ;; LATIN CAPITAL LETTER I WITH ACUTE
+ ("O'" ?Ó) ;; LATIN CAPITAL LETTER O WITH ACUTE
+ ("U'" ?Ú) ;; LATIN CAPITAL LETTER U WITH ACUTE
  ;; “Grave, marking emphasis on short vowels”:
  ("a`" ?à) ;; LATIN SMALL LETTER A WITH GRAVE
- ("e`" ?è) ;; LATIN SMALL LETTER E WITH GRAVE 
- ("i`" ?ì) ;; LATIN SMALL LETTER I WITH GRAVE 
- ("o`" ?ò) ;; LATIN SMALL LETTER O WITH GRAVE 
- ("u`" ?ù) ;; LATIN SMALL LETTER U WITH GRAVE 
- ("A`" ?À) ;; LATIN CAPITAL LETTER A WITH GRAVE 
- ("E`" ?È) ;; LATIN CAPITAL LETTER E WITH GRAVE 
- ("I`" ?Ì) ;; LATIN CAPITAL LETTER I WITH GRAVE 
- ("O`" ?Ò) ;; LATIN CAPITAL LETTER O WITH GRAVE 
+ ("e`" ?è) ;; LATIN SMALL LETTER E WITH GRAVE
+ ("i`" ?ì) ;; LATIN SMALL LETTER I WITH GRAVE
+ ("o`" ?ò) ;; LATIN SMALL LETTER O WITH GRAVE
+ ("u`" ?ù) ;; LATIN SMALL LETTER U WITH GRAVE
+ ("A`" ?À) ;; LATIN CAPITAL LETTER A WITH GRAVE
+ ("E`" ?È) ;; LATIN CAPITAL LETTER E WITH GRAVE
+ ("I`" ?Ì) ;; LATIN CAPITAL LETTER I WITH GRAVE
+ ("O`" ?Ò) ;; LATIN CAPITAL LETTER O WITH GRAVE
  ("U`" ?Ù) ;; LATIN CAPITAL LETTER U WITH GRAVE
  ;; “Cater for the use of many French words and use of the circumflex
  ;; in Frisian.”  Yudit used `;' for cedilla.
- ("c," ?ç) ;; LATIN SMALL LETTER C WITH CEDILLA 
- ("C," ?Ç) ;; LATIN CAPITAL LETTER C WITH CEDILLA 
- ("a^" ?â) ;; LATIN SMALL LETTER A WITH CIRCUMFLEX 
- ("e^" ?ê) ;; LATIN SMALL LETTER E WITH CIRCUMFLEX 
- ("i^" ?î) ;; LATIN SMALL LETTER I WITH CIRCUMFLEX 
- ("o^" ?ô) ;; LATIN SMALL LETTER O WITH CIRCUMFLEX 
- ("u^" ?û) ;; LATIN SMALL LETTER U WITH CIRCUMFLEX 
- ("A^" ?Â) ;; LATIN CAPITAL LETTER A WITH CIRCUMFLEX 
- ("E^" ?Ê) ;; LATIN CAPITAL LETTER E WITH CIRCUMFLEX 
- ("I^" ?Î) ;; LATIN CAPITAL LETTER I WITH CIRCUMFLEX 
- ("O^" ?Ô) ;; LATIN CAPITAL LETTER O WITH CIRCUMFLEX 
+ ("c," ?ç) ;; LATIN SMALL LETTER C WITH CEDILLA
+ ("C," ?Ç) ;; LATIN CAPITAL LETTER C WITH CEDILLA
+ ("a^" ?â) ;; LATIN SMALL LETTER A WITH CIRCUMFLEX
+ ("e^" ?ê) ;; LATIN SMALL LETTER E WITH CIRCUMFLEX
+ ("i^" ?î) ;; LATIN SMALL LETTER I WITH CIRCUMFLEX
+ ("o^" ?ô) ;; LATIN SMALL LETTER O WITH CIRCUMFLEX
+ ("u^" ?û) ;; LATIN SMALL LETTER U WITH CIRCUMFLEX
+ ("A^" ?Â) ;; LATIN CAPITAL LETTER A WITH CIRCUMFLEX
+ ("E^" ?Ê) ;; LATIN CAPITAL LETTER E WITH CIRCUMFLEX
+ ("I^" ?Î) ;; LATIN CAPITAL LETTER I WITH CIRCUMFLEX
+ ("O^" ?Ô) ;; LATIN CAPITAL LETTER O WITH CIRCUMFLEX
  ("U^" ?Û) ;; LATIN CAPITAL LETTER U WITH CIRCUMFLEX
  ;; “Follow the example of the Dutch POSIX locale, using ISO-8859-9 to
  ;; cater to the many Turks in Dutch society.”  Perhaps German methods
  ;; should do so too.  Follow turkish-alt-postfix here.
  ("i/" ?ı) ;; LATIN SMALL LETTER I WITH NO DOT
- ("s," ?ş) ;; LATIN SMALL LETTER S WITH CEDILLA 
- ("g^" ?ğ) ;; LATIN SMALL LETTER G WITH BREVE 
+ ("s," ?ş) ;; LATIN SMALL LETTER S WITH CEDILLA
+ ("g^" ?ğ) ;; LATIN SMALL LETTER G WITH BREVE
  ("I/" ?İ) ;; LATIN CAPITAL LETTER I WITH DOT ABOVE
- ("S," ?Ş) ;; LATIN CAPITAL LETTER S WITH CEDILLA 
- ("G^" ?Ğ) ;; LATIN CAPITAL LETTER G WITH BREVE 
+ ("S," ?Ş) ;; LATIN CAPITAL LETTER S WITH CEDILLA
+ ("G^" ?Ğ) ;; LATIN CAPITAL LETTER G WITH BREVE
  )
 
 ;; Originally from Yudit, discussed with Albertas Agejevas
@@ -1339,17 +1339,17 @@ of characters from a single Latin-N charset.
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
-  cedilla    |    /`   | c/ -> ç   c` -> ç
-  ogonek     |    `    | a` -> ą
+  cedilla    |    /\\=`   | c/ -> ç   c\\=` -> ç
+  ogonek     |    \\=`    | a\\=` -> ą
   breve      |    ~    | a~ -> ă
   caron      |    ~    | c~ -> č
   dbl. acute |    :    | o: -> ő
-  ring       |    `    | u` -> ů
-  dot        |    `    | z` -> ż
+  ring       |    \\=`    | u\\=` -> ů
+  dot        |    \\=`    | z\\=` -> ż
   stroke     |    /    | d/ -> đ
   nordic     |    /    | d/ -> ð   t/ -> þ   a/ -> å   e/ -> æ   o/ -> ø
   others     |   /<>   | s/ -> ß   ?/ -> ¿   !/ -> ¡
diff --git a/lisp/leim/quail/latin-post.el b/lisp/leim/quail/latin-post.el
index e8957eb..5106bd2 100644
--- a/lisp/leim/quail/latin-post.el
+++ b/lisp/leim/quail/latin-post.el
@@ -41,7 +41,7 @@
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
@@ -390,7 +390,7 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   dot        |    .    | c. -> ċ   i. -> ı   I. -> İ
@@ -746,7 +746,7 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
@@ -1005,8 +1005,8 @@ OEE -> OE
  "french-postfix" "French" "FR<" t
  "French (Français) input method with postfix modifiers
 
-` pour grave, ' pour aigu, ^ pour circonflexe, et \" pour tréma.
-Par exemple: a` -> à   e' -> é.
+\\=` pour grave, ' pour aigu, ^ pour circonflexe, et \" pour tréma.
+Par exemple: a\\=` -> à   e' -> é.
 
 Ç, «, et » sont produits par C,, <<, et >>.
 
@@ -1117,7 +1117,7 @@ szz -> sz
  ("aue" ["aue"])
  ("Aue" ["Aue"])
  ("que" ["que"])
- ("Que" ["Que"]) 
+ ("Que" ["Que"])
 )
 
 (quail-define-package
@@ -1186,15 +1186,15 @@ Doubling the postfix separates the letter and postfix: e.g. a'' -> a'
  "italian-postfix" "Latin-1" "IT<" t
  "Italian (Italiano) input method with postfix modifiers
 
-a` -> à    A` -> À    e' -> é    << -> «
-e` -> è    E` -> È    E' -> É    >> -> »
-i` -> ì    I` -> Ì               o_ -> º
-o` -> ò    O` -> Ò               a_ -> ª
-u` -> ù    U` -> Ù
+a\\=` -> à    A\\=` -> À    e' -> é    << -> «
+e\\=` -> è    E\\=` -> È    E' -> É    >> -> »
+i\\=` -> ì    I\\=` -> Ì               o_ -> º
+o\\=` -> ò    O\\=` -> Ò               a_ -> ª
+u\\=` -> ù    U\\=` -> Ù
 
 Typewriter-style italian characters.
 
-Doubling the postfix separates the letter and postfix: e.g. a`` -> a`
+Doubling the postfix separates the letter and postfix: e.g. a\\=`\\=` -> a\\=`
 " nil t nil nil nil nil nil nil nil nil t)
 
 (quail-define-rules
@@ -2090,7 +2090,7 @@ of characters from a single Latin-N charset.
              | postfix | examples
  ------------+---------+----------
   acute      |    '    | a' -> á
-  grave      |    `    | a` -> à
+  grave      |    \\=`    | a\\=` -> à
   circumflex |    ^    | a^ -> â
   diaeresis  |    \"    | a\" -> ä
   tilde      |    ~    | a~ -> ã
diff --git a/lisp/leim/quail/latin-pre.el b/lisp/leim/quail/latin-pre.el
index 41552b5..4e60d9c 100644
--- a/lisp/leim/quail/latin-pre.el
+++ b/lisp/leim/quail/latin-pre.el
@@ -53,7 +53,7 @@
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á, '' -> ´
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"a -> ä  \"\" -> ¨
     tilde    |   ~    | ~a -> ã
@@ -184,7 +184,7 @@
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á   '' -> ´
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   diaeresis  |   \"    | \"i -> ï   \"\" -> ¨
     tilde    |   ~    | ~n -> ñ
    cedilla   |   ~    | ~c -> ç
@@ -259,7 +259,7 @@ Key translation rules are:
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'e -> é
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"i -> ï
    cedilla   | ~ or , | ~c -> ç   ,c -> ç
@@ -398,7 +398,7 @@ Key translation rules are:
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á   '' -> ´
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"u -> ü
     tilde    |   ~    | ~a -> ã
@@ -489,9 +489,9 @@ Key translation rules are:
   diaeresis  |   \"    | \"a -> ä   \"\" -> ¨
     breve    |   ~    | ~a -> ă
     caron    |   ~    | ~c -> č
-   cedilla   |   `    | `c -> ç   `e -> ?ę
-    misc     | ' ` ~  | 'd -> đ   `l -> ł   `z -> ż   ~o -> ő   ~u -> ű
-   symbol    |   ~    | `. -> ˙   ~~ -> ˘   ~. -> ?¸
+   cedilla   |   \\=`    | \\=`c -> ç   \\=`e -> ?ę
+    misc     | ' \\=` ~  | 'd -> đ   \\=`l -> ł   \\=`z -> ż   ~o -> ő   ~u -> ű
+   symbol    |   ~    | \\=`. -> ˙   ~~ -> ˘   ~. -> ?¸
 " nil t nil nil nil nil nil nil nil nil t)
 
 (quail-define-rules
@@ -596,13 +596,13 @@ Key translation rules are:
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á   '' -> ?´
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"a -> ä   \"\" -> ¨
    cedilla   |   ~    | ~c -> ç   ~s -> ş   ~~ -> ¸
   dot above  |   / .  | /g -> ġ   .o -> ġ
     misc     | \" ~ /  | \"s -> ß   ~g -> ğ   ~u -> ŭ   /h -> ħ   /i -> ı
-   symbol    |   ~    | ~` -> ˘   /# -> £   /$ -> ¤   // -> °
+   symbol    |   ~    | ~\\=` -> ˘   /# -> £   /$ -> ¤   // -> °
 " nil t nil nil nil nil nil nil nil nil t)
 
 (quail-define-rules
@@ -737,7 +737,7 @@ For example, the character named `aogonek' is obtained by `/a'."
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"a -> ä, \"Y -> Ÿ
     tilde    |   ~    | ~a -> ã
@@ -872,7 +872,7 @@ For example, the character named `aogonek' is obtained by `/a'."
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^w -> ŵ
   diaeresis  |   \"    | \"a -> ä
   dot above  |   .    | .b -> ḃ
@@ -997,7 +997,7 @@ of characters from a single Latin-N charset.
     effect   | prefix | examples
  ------------+--------+----------
     acute    |   '    | 'a -> á, '' -> ´
-    grave    |   `    | `a -> à
+    grave    |   \\=`    | \\=`a -> à
   circumflex |   ^    | ^a -> â
   diaeresis  |   \"    | \"a -> ä  \"\" -> ¨
     tilde    |   ~    | ~a -> ã
diff --git a/lisp/leim/quail/thai.el b/lisp/leim/quail/thai.el
index 2554686..72e5020 100644
--- a/lisp/leim/quail/thai.el
+++ b/lisp/leim/quail/thai.el
@@ -47,7 +47,7 @@
 
 The difference from the ordinal Thai keyboard:
     ‘฿’ and ‘๏’ are assigned to ‘\\’ and ‘|’ respectively,
-    ‘ฃ’ and ‘ฅ’ are assigned to ‘`’ and ‘~’ respectively,
+    ‘ฃ’ and ‘ฅ’ are assigned to ‘\\=`’ and ‘~’ respectively,
     Don't know where to assign characters ‘๚’ and ‘๛’."
  nil t t t t nil nil nil nil nil t)
 
diff --git a/lisp/leim/quail/tibetan.el b/lisp/leim/quail/tibetan.el
index a54cbdc..1313f56 100644
--- a/lisp/leim/quail/tibetan.el
+++ b/lisp/leim/quail/tibetan.el
@@ -141,7 +141,7 @@
 
   NOT SPECIFIED IN EXT. WYLIE:
     +--------------------------------------------------------+
-    |ྂ = ~ |ྃ = ` |྄ = , |྅ = @ |༷ = _o|༵ = _O|༆ = ^|
+    |ྂ = ~ |ྃ = \\=` |྄ = , |྅ = @ |༷ = _o|༵ = _O|༆ = ^|
     +--------------------------------------------------------+
     |ྈ = x |ྉ = X |྆ = v |྇ = V |ྊ = q |ྋ = Q |
     +-----------------------------------------------+
diff --git a/lisp/leim/quail/viqr.el b/lisp/leim/quail/viqr.el
index c5c1c94..570a16b 100644
--- a/lisp/leim/quail/viqr.el
+++ b/lisp/leim/quail/viqr.el
@@ -53,7 +53,7 @@
     horn     |    +    | o+ -> ơ
  ------------+---------+----------
     acute    |    '    | a' -> á
-    grave    |    `    | a` -> à
+    grave    |    \\=`    | a\\=` -> à
   hook above |    ?    | a? -> ả
     tilde    |    ~    | a~ -> ã
    dot below |    .    | a. -> ạ
diff --git a/lisp/obsolete/iso-acc.el b/lisp/obsolete/iso-acc.el
index eaf732e..499a9da 100644
--- a/lisp/obsolete/iso-acc.el
+++ b/lisp/obsolete/iso-acc.el
@@ -272,7 +272,7 @@ See the function `iso-accents-mode'."
 
 (defcustom iso-accents-enable '(?' ?` ?^ ?\" ?~ ?/)
   "List of accent keys that become prefixes in ISO Accents mode.
-The default is (?' ?` ?^ ?\" ?~ ?/), which contains all the supported
+The default is (?' ?\\=` ?^ ?\" ?~ ?/), which contains all the supported
 accent keys.  If you set this variable to a list in which some of those
 characters are missing, the missing ones do not act as accents.
 
@@ -346,7 +346,7 @@ the language you choose)."
   "Toggle ISO Accents mode, in which accents modify the following letter.
 This permits easy insertion of accented characters according to ISO-8859-1.
 When Iso-accents mode is enabled, accent character keys
-\(`, ', \", ^, / and ~) do not self-insert; instead, they modify the following
+\(\\=`, ', \", ^, / and ~) do not self-insert; instead, they modify the following
 letter key so that it inserts an ISO accented letter.
 
 You can customize ISO Accents mode to a particular language
diff --git a/lisp/obsolete/scribe.el b/lisp/obsolete/scribe.el
index 122b1bf..68b2208 100644
--- a/lisp/obsolete/scribe.el
+++ b/lisp/obsolete/scribe.el
@@ -50,7 +50,7 @@
   :group 'scribe)
 
 (defcustom scribe-electric-quote nil
-  "Non-nil makes insert of double quote use `` or '' depending on context."
+  "Non-nil makes insert of double quote use \\=`\\=` or '' depending on context."
   :type 'boolean
   :group 'scribe)
 
@@ -124,7 +124,7 @@ Interesting variables:
   Non-nil makes Scribe mode use a different style of paragraph separation.
 
 `scribe-electric-quote'
-  Non-nil makes insert of double quote use `` or '' depending on context.
+  Non-nil makes insert of double quote use \\=`\\=` or '' depending on context.
 
 `scribe-electric-parenthesis'
   Non-nil makes an open-parenthesis char (one of `([<{')
@@ -265,8 +265,8 @@ to skip backward."
   (forward-char -1))
 
 (defun scribe-insert-quote (count)
-  "Insert ``, '' or \" according to preceding character.
-If `scribe-electric-quote' is non-nil, insert ``, '' or \" according
+  "Insert \\=`\\=`, '' or \" according to preceding character.
+If `scribe-electric-quote' is non-nil, insert \\=`\\=`, '' or \" according
 to preceding character.  With numeric arg N, always insert N \" characters.
 Else just insert \"."
   (interactive "P")
diff --git a/lisp/obsolete/sregex.el b/lisp/obsolete/sregex.el
index 4959072..80b2c92 100644
--- a/lisp/obsolete/sregex.el
+++ b/lisp/obsolete/sregex.el
@@ -416,7 +416,7 @@ Here are the clauses allowed in an `sregex' or `sregexq' expression:
   given set.  See below for how to construct a CHAR-CLAUSE.
 
 - the symbol `bot'
-  Stands for \"\\\\`\", matching the empty string at the beginning of
+  Stands for \"\\\\\\=`\", matching the empty string at the beginning of
   text (beginning of a string or of a buffer).
 
 - the symbol `eot'
diff --git a/lisp/obsolete/tpu-edt.el b/lisp/obsolete/tpu-edt.el
index c5959d1..9814265 100644
--- a/lisp/obsolete/tpu-edt.el
+++ b/lisp/obsolete/tpu-edt.el
@@ -648,7 +648,7 @@ GOLD is the ASCII 7-bit escape sequence <ESC>OP.")
 (make-variable-buffer-local 'tpu-mark-flag)
 
 (defun tpu-set-mode-line (for-tpu)
-  "Set ``minor-mode-alist'' for TPU-edt, or reset it to default Emacs."
+  "Set `minor-mode-alist' for TPU-edt, or reset it to default Emacs."
   (let ((entries '((tpu-newline-and-indent-p tpu-newline-and-indent-string)
                    (tpu-rectangular-p tpu-rectangle-string)
                    (tpu-direction-string tpu-direction-string)
diff --git a/lisp/obsolete/tpu-mapper.el b/lisp/obsolete/tpu-mapper.el
index 4c5ea13..3115038 100644
--- a/lisp/obsolete/tpu-mapper.el
+++ b/lisp/obsolete/tpu-mapper.el
@@ -81,7 +81,7 @@ suit your tastes (or to cope with those silly Sun and PC keypads).
 Finally, you will be prompted for the name of the file to store the key
 definitions.  If you chose the default, TPU-edt will find it and load it
 automatically.  If you specify a different file name, you will need to
-set the variable ``tpu-xkeys-file'' before starting TPU-edt.  Here's how
+set the variable `tpu-xkeys-file' before starting TPU-edt.  Here's how
 you might go about doing that in your init file.
 
   (setq tpu-xkeys-file (expand-file-name \"~/.my-emacs-x-keys\"))
diff --git a/lisp/org/ob-core.el b/lisp/org/ob-core.el
index fd14462..f767a4e 100644
--- a/lisp/org/ob-core.el
+++ b/lisp/org/ob-core.el
@@ -2583,7 +2583,7 @@ block but are passed literally to the \"example-block\"."
 (defun org-babel-read (cell &optional inhibit-lisp-eval)
   "Convert the string value of CELL to a number if appropriate.
 Otherwise if cell looks like lisp (meaning it starts with a
-\"(\", \"'\", \"`\" or a \"[\") then read it as lisp,
+\"(\", \"'\", \"\\=`\" or a \"[\") then read it as lisp,
 otherwise return it unmodified as a string.  Optional argument
 NO-LISP-EVAL inhibits lisp evaluation for situations in which is
 it not appropriate."
diff --git a/lisp/org/org-agenda.el b/lisp/org/org-agenda.el
index 8f7611f..9f4caab 100644
--- a/lisp/org/org-agenda.el
+++ b/lisp/org/org-agenda.el
@@ -5712,7 +5712,7 @@ This function is invoked if `org-agenda-todo-ignore-deadlines',
    (let ((calendar-date-style 'european)	(european-calendar-style t))
      (diary-date day month year mark))))
 
-;; Define the` org-class' function
+;; Define the `org-class' function
 (defun org-class (y1 m1 d1 y2 m2 d2 dayname &rest skip-weeks)
   "Entry applies if date is between dates on DAYNAME, but skips SKIP-WEEKS.
 DAYNAME is a number between 0 (Sunday) and 6 (Saturday).
diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el
index 2acfc10..7390aa1 100644
--- a/lisp/progmodes/cperl-mode.el
+++ b/lisp/progmodes/cperl-mode.el
@@ -7631,7 +7631,7 @@ $8	Match of the 8th set of parentheses in the last match (auto-local).
 $9	Match of the 9th set of parentheses in the last match (auto-local).
 $&	The string matched by the last pattern match (auto-local).
 $'	The string after what was matched by the last match (auto-local).
-$`	The string before what was matched by the last match (auto-local).
+$\\=`	The string before what was matched by the last match (auto-local).
 
 $(	The real gid of this process.
 $)	The effective gid of this process.
@@ -7647,7 +7647,7 @@ $;	Subscript separator for multi-dim array emulation.  Default \"\\034\".
 $<	The real uid of this process.
 $=	The page length of the current output channel.  Default is 60 lines.
 $>	The effective uid of this process.
-$?	The status returned by the last ``, pipe close or `system'.
+$?	The status returned by the last \\=`\\=`, pipe close or `system'.
 $@	The perl error message from the last eval or do @var{EXPR} command.
 $ARGV	The name of the current file used with <> .
 $[	Deprecated: The index of the first element/char in an array/string.
@@ -7888,7 +7888,7 @@ printf [FILEHANDLE] (FORMAT,LIST)
 push(ARRAY,LIST)
 q/STRING/	Synonym for 'STRING'
 qq/STRING/	Synonym for \"STRING\"
-qx/STRING/	Synonym for `STRING`
+qx/STRING/	Synonym for \\=`STRING\\=`
 rand[(EXPR)]
 read(FILEHANDLE,SCALAR,LENGTH[,OFFSET])
 readdir(DIRHANDLE)
@@ -8007,7 +8007,7 @@ pos STRING    Set/Get end-position of the last match over this string, see \\G.
 quotemeta [ EXPR ]	Quote regexp metacharacters.
 qw/WORD1 .../		Synonym of split('', 'WORD1 ...')
 readline FH	Synonym of <FH>.
-readpipe CMD	Synonym of `CMD`.
+readpipe CMD	Synonym of \\=`CMD\\=`.
 ref [ EXPR ]	Type of EXPR when dereferenced.
 sysopen FH, FILENAME, MODE [, PERM]	(MODE is numeric, see Fcntl.)
 tie VAR, PACKAGE, LIST	Hide an object behind a simple Perl variable.
diff --git a/lisp/progmodes/f90.el b/lisp/progmodes/f90.el
index 6264d3b..9ed5173 100644
--- a/lisp/progmodes/f90.el
+++ b/lisp/progmodes/f90.el
@@ -1113,7 +1113,7 @@ For fixed format code, use `fortran-mode'.
  indented line.
 \\[f90-indent-subprogram] indents the current subprogram.
 
-Type `? or `\\[help-command] to display a list of built-in\
+Type \\=`? or \\=`\\[help-command] to display a list of built-in\
  abbrevs for F90 keywords.
 
 Key definitions:
@@ -2267,7 +2267,7 @@ Leave point at the end of line."
 ;; Abbrevs and keywords.
 
 (defun f90-abbrev-start ()
-  "Typing `\\[help-command] or `? lists all the F90 abbrevs.
+  "Typing \\=`\\[help-command] or \\=`? lists all the F90 abbrevs.
 Any other key combination is executed normally."
   (interactive "*")
   (self-insert-command 1)
diff --git a/lisp/progmodes/idlwave.el b/lisp/progmodes/idlwave.el
index 45f080c..2635a82 100644
--- a/lisp/progmodes/idlwave.el
+++ b/lisp/progmodes/idlwave.el
@@ -742,8 +742,8 @@ The actions that can be performed are listed in `idlwave-indent-action-table'."
 
 (defcustom idlwave-abbrev-start-char "\\"
   "A single character string used to start abbreviations in abbrev mode.
-Possible characters to chose from: ~`\%
-or even '?'.  '.' is not a good choice because it can make structure
+Possible characters to choose from: ~\\=`\%
+or even ‘?’.  ‘.’ is not a good choice because it can make structure
 field names act like abbrevs in certain circumstances.
 
 Changes to this in `idlwave-mode-hook' will have no effect.  Instead a user
diff --git a/lisp/progmodes/sh-script.el b/lisp/progmodes/sh-script.el
index e4d16eb..537b180 100644
--- a/lisp/progmodes/sh-script.el
+++ b/lisp/progmodes/sh-script.el
@@ -921,7 +921,7 @@ See `sh-feature'.")
      (:foreground "magenta"))
     (t
      (:weight bold)))
-  "Face to show quoted execs like `blabla`."
+  "Face to show quoted execs like \\=`blabla\\=`."
   :group 'sh-indentation)
 (define-obsolete-face-alias 'sh-heredoc-face 'sh-heredoc "22.1")
 (defvar sh-heredoc-face 'sh-heredoc)
diff --git a/lisp/progmodes/verilog-mode.el b/lisp/progmodes/verilog-mode.el
index 4b0cb0f..11b7561 100644
--- a/lisp/progmodes/verilog-mode.el
+++ b/lisp/progmodes/verilog-mode.el
@@ -597,11 +597,11 @@ Set to 0 to get them list right under containing block."
   "How to treat macro expansions in a declaration.
 If nil, indent as:
 	input [31:0] a;
-	input        `CP;
+	input        \\=`CP;
 	output       c;
 If non nil, treat as:
 	input [31:0] a;
-	input `CP    ;
+	input \\=`CP    ;
 	output       c;"
   :group 'verilog-mode-indent
   :type 'boolean)
@@ -628,7 +628,7 @@ Set to 0 to get such code to start at the left side of the screen."
 (put 'verilog-indent-level-behavioral 'safe-local-variable 'integerp)
 
 (defcustom verilog-indent-level-directive 1
-  "Indentation to add to each level of `ifdef declarations.
+  "Indentation to add to each level of \\=`ifdef declarations.
 Set to 0 to have all directives start at the left side of the screen."
   :group 'verilog-mode-indent
   :type 'integer)
@@ -733,8 +733,8 @@ file referenced.  If false, this is not supported."
 
 (defcustom verilog-auto-declare-nettype nil
   "Non-nil specifies the data type to use with `verilog-auto-input' etc.
-Set this to \"wire\" if the Verilog code uses \"`default_nettype
-none\".  Note using `default_nettype none isn't recommended practice; this
+Set this to \"wire\" if the Verilog code uses \"\\=`default_nettype
+none\".  Note using \\=`default_nettype none isn't recommended practice; this
 mode is experimental."
   :version "24.1"  ;; rev670
   :group 'verilog-mode-actions
@@ -3670,7 +3670,7 @@ Variables controlling indentation/edit style:
    Set to 0 to get such code to lined up underneath the task or
    function keyword.
  `verilog-indent-level-directive'     (default 1)
-   Indentation of `ifdef/`endif blocks.
+   Indentation of \\=`ifdef/\\=`endif blocks.
  `verilog-cexp-indent'              (default 1)
    Indentation of Verilog statements broken across lines i.e.:
       if (a)
@@ -9235,9 +9235,9 @@ Optionally associate it with the specified enumeration ENUMNAME."
           (add-to-list (make-local-variable enumvar) defname)))))
 
 (defun verilog-read-defines (&optional filename recurse subcall)
-  "Read `defines and parameters for the current file, or optional FILENAME.
+  "Read \\=`defines and parameters for the current file, or optional FILENAME.
 If the filename is provided, `verilog-library-flags' will be used to
-resolve it.  If optional RECURSE is non-nil, recurse through `includes.
+resolve it.  If optional RECURSE is non-nil, recurse through \\=`includes.
 
 Parameters must be simple assignments to constants, or have their own
 \"parameter\" label rather than a list of parameters.  Thus:
@@ -9320,8 +9320,8 @@ warning message, you need to add to your init file:
 	    (forward-comment 99999)))))))
 
 (defun verilog-read-includes ()
-  "Read `includes for the current file.
-This will find all of the `includes which are at the beginning of lines,
+  "Read \\=`includes for the current file.
+This will find all of the \\=`includes which are at the beginning of lines,
 ignoring any ifdefs or multiline comments around them.
 `verilog-read-defines' is then performed on the current and each included
 file.
@@ -9343,11 +9343,11 @@ variable over and over when many modules are compiled together, put a test
 around the inside each include file:
 
 foo.v (an include file):
-	`ifdef _FOO_V	// include if not already included
-	`else
-	`define _FOO_V
+	\\=`ifdef _FOO_V	// include if not already included
+	\\=`else
+	\\=`define _FOO_V
 	... contents of file
-	`endif // _FOO_V"
+	\\=`endif // _FOO_V"
   ;;slow:  (verilog-read-defines nil t)
   (save-excursion
     (verilog-getopt-flags)
@@ -11184,7 +11184,7 @@ Limitations:
   `verilog-library-extensions', and being found in the same directory, or
   by changing the variable `verilog-library-flags' or
   `verilog-library-directories'.  Macros `modname are translated through the
-  vh-{name} Emacs variable, if that is not found, it just ignores the `.
+  vh-{name} Emacs variable, if that is not found, it just ignores the \\=`.
 
   In templates you must have one signal per line, ending in a ), or ));,
   and have proper () nesting, including a final ); to end the template.
@@ -12754,8 +12754,8 @@ Limitations:
   lists.  AUTOSENSE will thus exclude them, and add a /*memory or*/ comment.
 
 Constant signals:
-  AUTOSENSE cannot always determine if a `define is a constant or a signal
-  (it could be in an include file for example).  If a `define or other signal
+  AUTOSENSE cannot always determine if a \\=`define is a constant or a signal
+  (it could be in an include file for example).  If a \\=`define or other signal
   is put into the AUTOSENSE list and is not desired, use the AUTO_CONSTANT
   declaration anywhere in the module (parenthesis are required):
 
@@ -12870,8 +12870,8 @@ them to a one.
 AUTORESET may try to reset arrays or structures that cannot be
 reset by a simple assignment, resulting in compile errors.  This
 is a feature to be taken as a hint that you need to reset these
-signals manually (or put them into a \"`ifdef NEVER signal<=`0;
-`endif\" so Verilog-Mode ignores them.)
+signals manually (or put them into a \"\\=`ifdef NEVER signal<=\\=`0;
+\\=`endif\" so Verilog-Mode ignores them.)
 
 An example:
 
@@ -13041,27 +13041,27 @@ Typing \\[verilog-auto] will make this into:
 
 (defun verilog-auto-undef ()
   "Expand AUTOUNDEF statements, as part of \\[verilog-auto].
-Take any `defines since the last AUTOUNDEF in the current file
-and create `undefs for them.  This is used to insure that
-file-local defines do not pollute the global `define name space.
+Take any \\=`defines since the last AUTOUNDEF in the current file
+and create \\=`undefs for them.  This is used to insure that
+file-local defines do not pollute the global \\=`define name space.
 
 Limitations:
-  AUTOUNDEF presumes any identifier following `define is the
-  name of a define.  Any `ifdefs are ignored.
+  AUTOUNDEF presumes any identifier following \\=`define is the
+  name of a define.  Any \\=`ifdefs are ignored.
 
-  AUTOUNDEF suppresses creating an `undef for any define that was
-  `undefed before the AUTOUNDEF.  This may be used to work around
-  the ignoring of `ifdefs as shown below.
+  AUTOUNDEF suppresses creating an \\=`undef for any define that was
+  \\=`undefed before the AUTOUNDEF.  This may be used to work around
+  the ignoring of \\=`ifdefs as shown below.
 
 An example:
 
-	`define XX_FOO
-	`define M_BAR(x)
-	`define M_BAZ
+	\\=`define XX_FOO
+	\\=`define M_BAR(x)
+	\\=`define M_BAZ
 	...
-	`ifdef NEVER
-	  `undef M_BAZ	// Emacs will see this and not `undef M_BAZ
-	`endif
+	\\=`ifdef NEVER
+	  \\=`undef M_BAZ	// Emacs will see this and not \\=`undef M_BAZ
+	\\=`endif
 	...
 	/*AUTOUNDEF*/
 
@@ -13070,8 +13070,8 @@ Typing \\[verilog-auto] will make this into:
 	...
 	/*AUTOUNDEF*/
 	// Beginning of automatic undefs
-	`undef XX_FOO
-	`undef M_BAR
+	\\=`undef XX_FOO
+	\\=`undef M_BAR
 	// End of automatics
 
 You may also provide an optional regular expression, in which case only
@@ -13466,12 +13466,12 @@ Using \\[describe-function], see also:
     `verilog-auto-reset'        for AUTORESET flop resets
     `verilog-auto-sense'        for AUTOSENSE or AS always sensitivity lists
     `verilog-auto-tieoff'       for AUTOTIEOFF output tieoffs
-    `verilog-auto-undef'        for AUTOUNDEF `undef of local `defines
+    `verilog-auto-undef'        for AUTOUNDEF \\=`undef of local \\=`defines
     `verilog-auto-unused'       for AUTOUNUSED unused inputs/inouts
     `verilog-auto-wire'         for AUTOWIRE instantiation wires
 
-    `verilog-read-defines'      for reading `define values
-    `verilog-read-includes'     for reading `includes
+    `verilog-read-defines'      for reading \\=`define values
+    `verilog-read-includes'     for reading \\=`includes
 
 If you have bugs with these autos, please file an issue at
 URL `http://www.veripool.org/verilog-mode' or contact the AUTOAUTHOR
diff --git a/lisp/skeleton.el b/lisp/skeleton.el
index 1363422..d23488b 100644
--- a/lisp/skeleton.el
+++ b/lisp/skeleton.el
@@ -481,7 +481,7 @@ This allows for context-sensitive checking whether pairing is appropriate.")
 Each alist element, which looks like (ELEMENT ...), is passed to
 `skeleton-insert' with no interactor.  Variable `str' does nothing.
 
-Elements might be (?` ?` _ \"''\"), (?\\( ?  _ \" )\") or (?{ \\n > _ \\n ?} >).")
+Elements might be (?\\=` ?\\=` _ \"''\"), (?\\( ?  _ \" )\") or (?{ \\n > _ \\n ?} >).")
 
 (defvar skeleton-pair-default-alist '((?( _ ?)) (?\))
 				      (?[ _ ?]) (?\])
diff --git a/lisp/textmodes/tex-mode.el b/lisp/textmodes/tex-mode.el
index 274cb4a..535b885 100644
--- a/lisp/textmodes/tex-mode.el
+++ b/lisp/textmodes/tex-mode.el
@@ -1034,7 +1034,7 @@ says which mode to use."
 (define-derived-mode plain-tex-mode tex-mode "TeX"
   "Major mode for editing files of input for plain TeX.
 Makes $ and } display the characters they match.
-Makes \" insert `` when it seems to be the beginning of a quotation,
+Makes \" insert \\=`\\=` when it seems to be the beginning of a quotation,
 and '' when it appears to be the end; it inserts \" only after a \\.
 
 Use \\[tex-region] to run TeX on the current region, plus a \"header\"
@@ -1080,7 +1080,7 @@ special subshell is initiated, the hook `tex-shell-hook' is run."
 (define-derived-mode latex-mode tex-mode "LaTeX"
   "Major mode for editing files of input for LaTeX.
 Makes $ and } display the characters they match.
-Makes \" insert `` when it seems to be the beginning of a quotation,
+Makes \" insert \\=`\\=` when it seems to be the beginning of a quotation,
 and '' when it appears to be the end; it inserts \" only after a \\.
 
 Use \\[tex-region] to run LaTeX on the current region, plus the preamble
@@ -1162,7 +1162,7 @@ subshell is initiated, `tex-shell-hook' is run."
 (define-derived-mode slitex-mode latex-mode "SliTeX"
   "Major mode for editing files of input for SliTeX.
 Makes $ and } display the characters they match.
-Makes \" insert `` when it seems to be the beginning of a quotation,
+Makes \" insert \\=`\\=` when it seems to be the beginning of a quotation,
 and '' when it appears to be the end; it inserts \" only after a \\.
 
 Use \\[tex-region] to run SliTeX on the current region, plus the preamble
@@ -1296,7 +1296,7 @@ Entering SliTeX mode runs the hook `text-mode-hook', then the hook
 
 (defun tex-insert-quote (arg)
   "Insert the appropriate quote marks for TeX.
-Inserts the value of `tex-open-quote' (normally ``) or `tex-close-quote'
+Inserts the value of `tex-open-quote' (normally \\=`\\=`) or `tex-close-quote'
 \(normally '') depending on the context.  With prefix argument, always
 inserts \" characters."
   (interactive "*P")
diff --git a/lisp/textmodes/texinfmt.el b/lisp/textmodes/texinfmt.el
index e7b6835..cab4f77 100644
--- a/lisp/textmodes/texinfmt.el
+++ b/lisp/textmodes/texinfmt.el
@@ -1287,7 +1287,7 @@ Leave point after argument."
 (put 'uref 'texinfo-format 'texinfo-format-uref)
 (defun texinfo-format-uref ()
   "Format URL and optional URL-TITLE.
-Insert ` ... ' around URL if no URL-TITLE argument;
+Insert \\=` ... ' around URL if no URL-TITLE argument;
 otherwise, insert URL-TITLE followed by URL in parentheses."
   (let ((args (texinfo-format-parse-args)))
     (texinfo-discard-command)
@@ -2447,7 +2447,7 @@ Use only the FILENAME arg; for Info, ignore the other arguments to @image."
 ;; not lead to inserted ` ... ' in a table, but does elsewhere.
 (put 'option 'texinfo-format 'texinfo-format-option)
 (defun texinfo-format-option ()
-  "Insert ` ... ' around arg unless inside a table; in that case, no quotes."
+  "Insert \\=` ... ' around arg unless inside a table; in that case, no quotes."
   ;; `looking-at-backward' not available in v. 18.57, 20.2
   (if (not (search-backward "\b"    ; searched-for character is a control-H
                     (line-beginning-position)
@@ -2494,7 +2494,7 @@ Enclose the verbatim text, including the delimiters, in braces.  Print
 text exactly as written (but not the delimiters) in a fixed-width.
 
 For example, @verb\{|@|\} results in @ and
-@verb\{+@'e?`!`+} results in @'e?`!`."
+@verb\{+@'e?\\=`!\\=`+} results in @'e?\\=`!\\=`."
 
   (let ((delimiter (buffer-substring-no-properties
 		    (1+ texinfo-command-end) (+ 2 texinfo-command-end))))
diff --git a/lisp/textmodes/texinfo.el b/lisp/textmodes/texinfo.el
index 895adbf..6b28249 100644
--- a/lisp/textmodes/texinfo.el
+++ b/lisp/textmodes/texinfo.el
@@ -689,7 +689,7 @@ Puts point on a blank line between them."
   '("example\\>" "smallexample\\>" "lisp\\>"))
 (defun texinfo-insert-quote (&optional arg)
   "Insert the appropriate quote mark for Texinfo.
-Usually inserts the value of `texinfo-open-quote' (normally ``) or
+Usually inserts the value of `texinfo-open-quote' (normally \\=`\\=`) or
 `texinfo-close-quote' (normally ''), depending on the context.
 With prefix argument or inside @code or @example, inserts a plain \"."
   (interactive "*P")
-- 
2.1.0

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/21/2015 10:21 AM, Paul Eggert wrote:

> And I found a
> reasonably simple way to put it in, namely, to modify
> substitute-command-keys so that it substitutes quotes as well, with a
> simple rule that can be done in one pass with only auxiliary boolean flag.

I'd make it a new function (the name doesn't fit), and pass the 
docstring contents through it, before giving them to 
substitute-command-keys.

And if you write it in Lisp, you could incorporate the special handling 
of quasiquotes relatively easily.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Dmitry Gutov wrote:
> I'd make it a new function (the name doesn't fit), and pass the docstring
> contents through it, before giving them to substitute-command-keys.

I originally wrote it that way, but it was harder for me to read.  (Also slower, 
though that doesn't matter these days.)  I couldn't find anybody that would want 
to call one function but not the other.  Plus, having them be separate functions 
introduces more opportunity for error, e.g., it wouldn't be correct to call the 
new function after calling substitute-command-keys.  So I figured we might as 
well leave them combined.

How about if we rename substitute-command-keys to describe it better? 
substitute-doc-string, perhaps?

> And if you write it in Lisp, you could incorporate the special handling of
> quasiquotes relatively easily.

Yes, I originally wrote it in Lisp too, but found that it was too tempting to 
implement complicated heuristics that would have been a pain to document.  (I 
even defended some of those heuristics in previous emails -- sorry!)  Doing it 
in C forced me to come up with something really simple and easy to explain.  I'd 
rather keep the simple rules now, even if we go back to Lisp (but why bother?).

bug#20385: [PATCH] Support curved quotes in doc strings

[Dmitry Gutov]

On 05/21/2015 05:58 PM, Paul Eggert wrote:

> I originally wrote it that way, but it was harder for me to read.

Two functions each doing less work is harder to read than one?

> (Also slower, though that doesn't matter these days.)

Still matters, but for larger inputs. Calling the quote substitution 
function before the keymaps-and-keys one should be fast enough, though.

> How about if we rename substitute-command-keys to describe it better?
> substitute-doc-string, perhaps?

format-doc-string? Anyway, a rename with an obsolete-alias should work, too.

> Yes, I originally wrote it in Lisp too, but found that it was too
> tempting to implement complicated heuristics that would have been a pain
> to document.

It's up to you. I think the handling of quasiquotes isn't hard to 
explain in writing, but in the end those snippets of code would be 
better surrounded with quotes after rendering, and then the quasiquote 
would simply need to be escaped.

> I'd rather keep the simple rules
> now, even if we go back to Lisp (but why bother?).

Having an Elisp implementation might be helpful if we want to apply a 
similar transformation via font-lock rules in the source buffers (I 
believe you expressed that interest). There will be some difference due 
to escaping, but some part might be reusable.

bug#20385: [PATCH] Support curved quotes in doc strings

[Andreas Schwab]

Paul Eggert <eggert@cs.ucla.edu> writes:

> Familiar to those who know Markdown, yes.  However, English quoting is
> more familiar to English writers, and far more people know English than
> know both English and Markdown.

The majority of English writers don't know about English quoting.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#20385: [PATCH] Support curved quotes in doc strings

[Drew Adams]

Our Esteemed Spokesman for Generation Z spake thus: 

> Although Emacs old-timers are used to quoting `like this', to
> newbies it's a weird and offputting relic from ancient history.

Ooooo.  Please show your research that led to that conclusion.

Just how did you measure the feelings and reactions of our
newbie population?  Did you poll newbie Emacs users, for
example?  What were the results?  How did you analyze them?

How did you compare the feelings of weirdness and
offputtingness our newbies expressed about `...' with those
they expressed about other aspects of Emacs, and about Emacs
in general?  How does their reaction to `...' compare with
their reaction to `M-x', `C-u C-x =', Lisp, and all the rest?

Where's the beef?

 - Decrepit soixante-huitards would like to know.

bug#20385: [PATCH] Support curved quotes in doc strings

[Paul Eggert]

Drew Adams wrote:
> How does their reaction to `...' compare with
> their reaction to `M-x', `C-u C-x =', Lisp, and all the rest?

They think Lisp is pretty cool, that control-meta-whatever is a pain, and that 
quoting `like this' is something a hidebound greybeard would do.

Although I don't have any formal research, I do have some experience.  Over the 
past decade my assistants and I have introduced Emacs to an average of about one 
new user per day.  Most were age 20 or less.  Many stop using Emacs soon after 
they learn it.  I'd like to help improve the retention rate.

bug#20385: [PATCH] Support curved quotes in doc strings

[Eli Zaretskii]

> Date: Fri, 15 May 2015 23:20:54 -0700
> From: Paul Eggert <eggert@cs.ucla.edu>
> 
> Although I don't have any formal research, I do have some experience.  Over the 
> past decade my assistants and I have introduced Emacs to an average of about one 
> new user per day.  Most were age 20 or less.  Many stop using Emacs soon after 
> they learn it.  I'd like to help improve the retention rate.

I'm not an "old-timer" who objects what you are trying to do, but do
you _really_ think, after all those years, that changing the quoting
style will affect the retention rate in any way?

Let's face it: we make this change (and others like it) because we
think it's right, not because we believe someone will like Emacs more
who didn't before.

bug#20385: missing charset for non-ASCII text/x-patch MIME parts in Thunderbird

[Ivan Shmakov]

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

>>>>> Dmitry Gutov <dgutov@yandex.ru> writes:

	[Moving to emacs-devel@ as the issue at hand is not exactly
	related to #20385.]

[…]

 > For some reason still unclear to me (I have English locale and
 > language set everywhere I can see), it displays a group of cyrillic
 > characters (тАШ) instead of the fancy quotes.  Which will complicate
 > reading small patches somewhat (ones I wouldn't open in an external
 > program otherwise).

	As I’ve pointed earlier [1], Thunderbird (on the /sending/ side)
	for some reason chooses /not/ to file the ‘charset’
	Content-Type: field for text/x-patch MIME parts.  In the absence
	of the explicitly-stated encoding, the receiving side may resort
	to guessing, or (if the buffer model so allows, and Emacs’
	/does/) may simply leave the content undecoded (as in:
	raw-text.)

	I presume this issue (the one of /not/ including the ‘charset’)
	is specific to Thunderbird.  As an example, please look at a
	fragment of the original patch thus MIMEd from Gnus.

[1] news:878ud0k8qh.fsf_-_@violet.siamics.net
    http://debbugs.gnu.org/20499#108

-- 
FSF associate member #7257  http://am-1.org/~ivan/      … 3013 B6A0 230E 334A

[-- Attachment #2: 0001-Support-curved-quotes-in-doc-strings.patch --]
[-- Type: text/x-patch, Size: 2822 bytes --]

From eb392195ffdb108228c981f92ca8b5766afdcff9 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Wed, 13 May 2015 00:10:00 -0700
Subject: [PATCH] Support curved quotes in doc strings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Emacs's traditional doc string style has been to quote symbols
`like this'.  This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better.  Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* 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/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
---
 doc/lispref/tips.texi           | 33 ++++++++++++++++++---------------
 etc/NEWS                        |  4 ++++
 lisp/cedet/srecode/texi.el      |  2 +-
 lisp/emacs-lisp/checkdoc.el     |  5 +++--
 lisp/emacs-lisp/lisp-mode.el    |  8 ++++----
 lisp/finder.el                  |  2 +-
 lisp/gnus/gnus-art.el           |  8 ++++----
 lisp/help-mode.el               |  7 ++++---
 lisp/international/mule-cmds.el |  2 +-
 lisp/progmodes/elisp-mode.el    | 24 +++++++++++++-----------
 lisp/wid-edit.el                |  2 +-
 11 files changed, 54 insertions(+), 43 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e4..912d746 100644
…
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 0a95783..dac3b1e 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -2863,7 +2863,7 @@ The following properties have special meanings for this widget:
   :type 'boolean
   :group 'widget-documentation)
 
-(defcustom widget-documentation-link-regexp "`\\([^\n`' ]+\\)'"
+(defcustom widget-documentation-link-regexp "[`‘]\\([^\n `'‘’]+\\)['’]"
   "Regexp for matching potential links in documentation strings.
 The first group should be the link itself."
   :type 'regexp
-- 
2.1.0

bug#20385: Support curved quotes in doc strings

[Ivan Shmakov]

>>>>> Dmitry Gutov <dgutov@yandex.ru> writes:
>>>>> On 05/13/2015 06:13 PM, Paul Eggert wrote:

[…]

 >> That's been proposed, but nobody has taken the time to do it.  Plus,
 >> it'd be One More Thing; it's simpler if doc strings are plain
 >> strings and are not little subsets of Markdown or whatever.

 > That's trivial, if there's agreement to do it. I don't really
 > understand the motivation for the original proposal (to switch away
 > from `...'), so it's not clear to me if font-locking would satisfy
 > it.

	That’s simple: the ` character is not a quotation mark at all.
	In fact, it’s the spacing variant of the very same diacritical
	mark as is shown above e in è.

	The rationale was that one can encode ‘è’ as ‘e\010`’ if there’s
	no “native” è character in the target (ASCII-based) encoding.
	Just like one may encode “bold” and “underline”; consider, say:

$ printf 'b\b_o\b_l\b_d\b_ u\bun\bnd\bde\ber\brl\bli\bin\bne\be\n' | less 

	The very same trick that up to this day is used by man(1).

[…]

-- 
FSF associate member #7257  http://am-1.org/~ivan/      … 3013 B6A0 230E 334A

bug#20385: Support curved quotes in doc strings

[Eli Zaretskii]

> From: Ivan Shmakov <ivan@siamics.net>
> Date: Thu, 14 May 2015 07:20:17 +0000
> 
> 	the ` character is not a quotation mark at all.
> 	In fact, it’s the spacing variant of the very same diacritical
> 	mark as is shown above e in è.

Any references for this?

bug#20385: Support curved quotes in doc strings

[Ivan Shmakov]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>>>>> From: Ivan Shmakov  Date: Thu, 14 May 2015 07:20:17 +0000

 >> The ` character is not a quotation mark at all.  In fact, it’s the
 >> spacing variant of the very same diacritical mark as is shown above
 >> e in è.

 > Any references for this?

	You mean, other than UnicodeData.txt and its derivatives?
	To quote NamesList.txt, for instance:

0060	GRAVE ACCENT
	* this is a spacing character
	x (modifier letter grave accent - 02CB)
	x (combining grave accent - 0300)
	x (reversed prime - 2035)
00B4	ACUTE ACCENT
	* this is a spacing character
	x (modifier letter prime - 02B9)
	x (modifier letter acute accent - 02CA)
	x (combining acute accent - 0301)
	x (prime - 2032)
	# 0020 0301
0300	COMBINING GRAVE ACCENT
	= Greek varia
	x (grave accent - 0060)
	x (modifier letter grave accent - 02CB)
0301	COMBINING ACUTE ACCENT
	= stress mark
	= Greek oxia, tonos
	x (apostrophe - 0027)
	x (acute accent - 00B4)
	x (modifier letter prime - 02B9)
	x (modifier letter acute accent - 02CA)
	x (greek tonos - 0384)

	I presume that if U+0060 was /not/ be meant to be a spacing
	grave accent – there would be some other code point for that
	purpose, just like there /is/ such a code point (U+00B4) for a
	spacing /acute/ accent.

	Given that standards are intended to document existing practice,
	I’d expect Unicode to note that ‘`’ may be used as a quotation
	mark in legacy applications.  I’d be surprised to find it
	/recommending/ such use, though.

	Also, while I have no copy of USAS X3.4-1968 at hand, RFC 20
	(which, AIUI, was intended to be a copy of it itself) has the
	following note:

   6/0         `           Grave Accent [2, 3] (Opening Single Quotation
                                   Mark)

[…]

      2 The use of the symbols in 2/2, 2/7, 2/12, 5/14, /6/0, and 7/14
   as diacritical marks is described in Appendix A, A5.2

	Alas, the appendices are not included in RFC 20.  Still, ECMA-6
	(which also names 6/0 GRAVE ACCENT) reads:

    B.2.3

    Composite graphic characters and repertoire

    ECMA-6 permits the construction of composite graphic characters by
    using the control characters BACKSPACE and CARRIAGE RETURN to image
    two or more graphic characters at the same character position.

-- 
FSF associate member #7257  http://am-1.org/~ivan/      … 3013 B6A0 230E 334A

bug#20385: Support curved quotes in doc strings

[Eli Zaretskii]

> From: Ivan Shmakov <ivan@siamics.net>
> Date: Thu, 14 May 2015 20:05:53 +0000
> 
> >>>>> Eli Zaretskii <eliz@gnu.org> writes:
> >>>>> From: Ivan Shmakov  Date: Thu, 14 May 2015 07:20:17 +0000
> 
>  >> The ` character is not a quotation mark at all.  In fact, it’s the
>  >> spacing variant of the very same diacritical mark as is shown above
>  >> e in è.
> 
>  > Any references for this?
> 
> 	You mean, other than UnicodeData.txt and its derivatives?
> 	To quote NamesList.txt, for instance:
> 
> 0060	GRAVE ACCENT
> 	* this is a spacing character
> 	x (modifier letter grave accent - 02CB)
> 	x (combining grave accent - 0300)
> 	x (reversed prime - 2035)

Where does it say that it can be combined with some base character as
a diacritical?

I see no decomposition in UnicodeData.txt that has 0060 as its part.

bug#20385: Support curved quotes in doc strings

[Ivan Shmakov]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>>>>> From: Ivan Shmakov  Date: Thu, 14 May 2015 20:05:53 +0000
>>>>> Eli Zaretskii <eliz@gnu.org> writes:
>>>>> From: Ivan Shmakov  Date: Thu, 14 May 2015 07:20:17 +0000

 >>>> The ` character is not a quotation mark at all.  In fact, it’s the
 >>>> spacing variant of the very same diacritical mark as is shown
 >>>> above e in è.

 >>> Any references for this?

 >> You mean, other than UnicodeData.txt and its derivatives?  To quote
 >> NamesList.txt, for instance:

 >> 0060 GRAVE ACCENT
 >> 	* this is a spacing character

[…]

 > Where does it say that it can be combined with some base character as
 > a diacritical?

	Where does it say that X can be combined with X to form a bold
	X?  Yet man(1) (or, rather, Nroff) uses that since time
	immemorial, and it still works with less(1) at the least.

	Obviously, that part of ASCII didn’t propagate to Unicode.
	That still hardly is a reason to use U+0060 (or any other
	spacing accent character) as a substitute to a quotation mark.

[…]

-- 
FSF associate member #7257  http://am-1.org/~ivan/      … 3013 B6A0 230E 334A

bug#20385: missing charset for non-ASCII text/x-patch MIME parts in Thunderbird

[Stephen J. Turnbull]

Ivan Shmakov writes:

 > 	As I’ve pointed earlier [1], Thunderbird (on the /sending/ side)
 > 	for some reason chooses /not/ to file the ‘charset’

File a bug on Thunderbird, then.  Absence of a charset parameter means
charset=US-ASCII, and Thunderbird should not be emitting US-ASCII MIME
parts with non-ASCII characters present.  Not even if the MTAs agree
to use SMTP8.

 > 	In the absence of the explicitly-stated encoding, the
 > 	receiving side may resort to guessing,

A conformant receiver SHOULD NOT guess, unless the user has given it
explicit permission to do that (of course, then anything is OK).  From
RFC 2046:

   4.1.2.  Charset Parameter

   A critical parameter that may be specified in the Content-Type
   field for "text/plain" data is the character set.  This is
   specified with a "charset" parameter, as in:

     Content-type: text/plain; charset=iso-8859-1

   Unlike some other parameter values, the values of the charset
   parameter are NOT case sensitive.  The default character set, which
   must be assumed in the absence of a charset parameter, is US-ASCII.

Note that technically speaking the MUST in this section only applies
to text/plain, and not to any other text content-type.  However, given
that the section says

   The specification for any future subtypes of "text" must specify
   whether or not they will also utilize a "charset" parameter, and
   may possibly restrict its values as well.  For other subtypes of
   "text" than "text/plain", the semantics of the "charset" parameter
   should be defined to be identical to those specified here for
   "text/plain", i.e., the body consists entirely of characters in the
   given charset.

Pretty clearly the intent is that the behavior of text/plain is to be
the default for other text content-types, unless *explicitly* stated
in the content-type spec.  See also section

   4.1.4.  Unrecognized Subtypes

   Unrecognized subtypes of "text" should be treated as subtype
   "plain" as long as the MIME implementation knows how to handle the
   charset.

This only makes sense when charset is unspecified if charset is
assumed to be US-ASCII.

 > 	I presume this issue (the one of /not/ including the ‘charset’)
 > 	is specific to Thunderbird.  As an example, please look at a
 > 	fragment of the original patch thus MIMEd from Gnus.

File a bug on Gnus, too. :-)

Of course Emacs should do what its user asks, but the default should
be to assume US-ASCII if there is no charset parameter, and to bitch
(not guess) if non-ASCII octets are seen.