Support curved quotes in doc strings

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.

21 files changed, 147 insertions, 124 deletions

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index cc1f0e42750..798b6700aac 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 5afd40e6727..8fe90129a5d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -908,6 +908,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 3c176aeaf05..35363337aee 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 be75f3765c1..b75a6609323 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 224d2c541b2..1321fbc4b7e 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 484b8cc43ad..c8641aed8bb 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)
@@ -738,7 +738,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 18361c8888f..4761ac5e6fc 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 24a04d445de..96b86aa21cc 100644
--- a/lisp/emacs-lisp/cl-generic.el
+++ b/lisp/emacs-lisp/cl-generic.el
@@ -876,11 +876,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 02b89e043e4..11d99849a97 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 6facf576055..ab01a109b7a 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 3d5afa3edd2..97e6bd63da9 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -2137,17 +2137,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 f6b11074af0..4366c0b9f23 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 47fab3cdc3d..306f2e27d57 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 7630afbdcf4..0ac9fb5b4de 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 4982ee54f46..346e1e158c2 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 f99e9165bce..3fc0ad2b403 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 2b8f6423172..1411c1aab9a 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 4b63cb8f565..c8cd76f5eb1 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 42e78f9c904..7ef758b58de 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) "")))))))))
 
 ;;; DIAGNOSIS
 
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index e06b920e5d7..b0700294637 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 d09214b42a3..295e2aada2a 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