Subject: Re: bug#20759: 25.0.50; pcase doc: (‘ QPAT) instead of (` QPAT)

From: Paul Eggert <[email-masked]>
Date: Fri, 12 Jun 2015 16:34:09 -0700

On 06/12/2015 05:20 AM, Michael Heerdegen wrote:
> Thinking again about this, maybe `PAT would be didactically better, in
> this special case of the pcase doc.

Sure, that's doable.  For consistency, the usage string computed 
automatically by "C-h f `" should be "`STRUCTURE", not "(\` 
STRUCTURE)".  I installed the attached.
>From 8f79b74f37e6787d27b69cac14091ec25b03a89e Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 12 Jun 2015 16:27:42 -0700
Subject: [PATCH] Document `X as "`X", not as "(` X)"

* lisp/help.el (help-split-fundoc, help--make-usage-docstring):
Document (backquote FOO) as "`FOO", not as "(` FOO)" (Bug#20759).
---
 lisp/help.el | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/lisp/help.el b/lisp/help.el
index b766cd0..d24fbfd 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1368,18 +1368,21 @@ DEF is the function whose usage we're looking for in DOCSTRING."
   ;; In cases where `function' has been fset to a subr we can't search for
   ;; function's name in the doc string so we use `fn' as the anonymous
   ;; function name instead.
-  (when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring))
+  (when (and docstring
+	     (string-match "\n\n(fn\\(\\( +\\([^\n ]+\\( .*\\)?\\)?\\)?)\\)\\'"
+			   docstring))
     (let ((doc (unless (zerop (match-beginning 0))
-		 (substring docstring 0 (match-beginning 0))))
-	  (usage-tail (match-string 1 docstring)))
-      (cons (format "(%s%s"
-		    ;; Replace `fn' with the actual function name.
-		    (if (symbolp def)
-			(help--docstring-quote
-			 (substring (format "%S" (list def)) 1 -1))
-		      'anonymous)
-		    usage-tail)
-	    doc))))
+                 (substring docstring 0 (match-beginning 0)))))
+      (cons (if (and (eq def '\`) (match-beginning 3) (not (match-beginning 4)))
+                (concat "\\=`" (match-string 3 docstring))
+              (let ((usage-tail (match-string 1 docstring)))
+                (format "(%s%s"
+                        ;; Replace `fn' with the actual function name.
+                        (if (symbolp def)
+                            (help--docstring-quote (format "%S" def))
+                          'anonymous)
+                        usage-tail)))
+            doc))))
 
 (defun help-add-fundoc-usage (docstring arglist)
   "Add the usage info to DOCSTRING.
@@ -1467,7 +1470,9 @@ the same names as used in the original source code, when possible."
 (define-obsolete-function-alias 'help-make-usage 'help--make-usage "25.1")
 
 (defun help--make-usage-docstring (fn arglist)
-  (help--docstring-quote (format "%S" (help--make-usage fn arglist))))
+  (help--docstring-quote
+   (let ((print-quoted (eq fn '\`)))
+     (format "%S" (help--make-usage fn arglist)))))
 
 
 (provide 'help)
-- 
2.1.0