bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

[Nikolay Kudryavtsev]

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

I had a docstring containing "C-c". Checkdoc gave me this suggestion:
"Keycode C-c embedded in doc string.  Use \\<keymap> & \\[function] instead"

Ok, but how? The relevant page of Elisp reference is (info "(elisp) Keys 
in Documentation"). But there they're called ‘\<MAPVAR>’ and 
‘\[COMMAND]’. So someone searching by the checkdoc names would never 
find them there. The docstring for substitute-command-keys is also 
consistent with the Elisp reference.

A trivial patch is included, since Elisp reference names seem more 
reasonable.

I'm not sure whether MAPVAR and COMMAND should be capitalized in the 
docstring, so someone else should decide on that.


[-- Attachment #2: 0001-checkdoc-Docstring-substitution-consistent-with-othe.patch --]
[-- Type: text/plain, Size: 2208 bytes --]

From 8618e86acd93a0d6fc02ccb2de493c2be1ac795a Mon Sep 17 00:00:00 2001
From: Nikolay Kudryavtsev <nikolay.kudryavtsev@gmail.com>
Date: Wed, 29 Sep 2021 22:33:49 +0300
Subject: [PATCH] checkdoc: Docstring substitution consistent with other docs.

* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
In error text return "MAPVAR" instead of "keymap" and "COMMAND"
instead of "function".
---
 lisp/emacs-lisp/checkdoc.el | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 5ea2f59ee6..16918746ca 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -254,7 +254,7 @@ checkdoc-ispell-lisp-words
 (defcustom checkdoc-max-keyref-before-warn nil
   "If non-nil, number of \\\\=[command-to-keystroke] tokens allowed in a doc string.
 Any more than this and a warning is generated suggesting that the construct
-\\\\={keymap} be used instead.  If the value is nil, never warn.
+\\\\={MAPVAR} be used instead.  If the value is nil, never warn.
 
 It used to not be practical to use `\\\\=[...]' very many times,
 because display of the documentation string would become slow.
@@ -1626,7 +1626,7 @@ checkdoc-this-string-valid-engine
 	     (checkdoc-create-error
 	      (concat
 	       "Keycode " (match-string 1)
-	       " embedded in doc string.  Use \\\\<keymap> & \\\\[function] "
+	       " embedded in doc string.  Use \\\\<MAPVAR> & \\\\[COMMAND] "
 	       "instead")
 	      (match-beginning 1) (match-end 1) t))))
      ;; Optionally warn about too many command substitutions.
@@ -1636,7 +1636,7 @@ checkdoc-this-string-valid-engine
                                      (1+ checkdoc-max-keyref-before-warn))
                   (not (re-search-forward "\\\\\\\\{\\w+}" e t)))
              (checkdoc-create-error
-              "Too many occurrences of \\[function].  Use \\{keymap} instead"
+              "Too many occurrences of \\[COMMAND].  Use \\{MAPVAR} instead"
               s (marker-position e)))))
      ;; Ambiguous quoted symbol.  When a symbol is both bound and fbound,
      ;; and is referred to in documentation, it should be prefixed with
-- 
2.32.0.windows.1

bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

[Eli Zaretskii]

> From: Nikolay Kudryavtsev <nikolay.kudryavtsev@gmail.com>
> Date: Wed, 29 Sep 2021 22:46:14 +0300
> 
> I had a docstring containing "C-c". Checkdoc gave me this suggestion:
> "Keycode C-c embedded in doc string.  Use \\<keymap> & \\[function] instead"
> 
> Ok, but how? The relevant page of Elisp reference is (info "(elisp) Keys 
> in Documentation"). But there they're called ‘\<MAPVAR>’ and 
> ‘\[COMMAND]’. So someone searching by the checkdoc names would never 
> find them there. The docstring for substitute-command-keys is also 
> consistent with the Elisp reference.
> 
> A trivial patch is included, since Elisp reference names seem more 
> reasonable.
> 
> I'm not sure whether MAPVAR and COMMAND should be capitalized in the 
> docstring, so someone else should decide on that.

They shouldn't be capitalized.  They are capitalized in Info because
that's what @var{..} produces in Info.  But in HTML and PDF, the
result is not capitalized, it is in italics instead.  So these shoiuld
not be capitalized in messages, either.

Thanks.

bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

[Nikolay Kudryavtsev]

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

Roger. s/r-d the patch.


[-- Attachment #2: 0001-checkdoc-Docstring-substitution-consistent-with-othe.patch --]
[-- Type: text/plain, Size: 2205 bytes --]

From 8618e86acd93a0d6fc02ccb2de493c2be1ac795a Mon Sep 17 00:00:00 2001
From: Nikolay Kudryavtsev <nikolay.kudryavtsev@gmail.com>
Date: Wed, 29 Sep 2021 22:33:49 +0300
Subject: [PATCH] checkdoc: Docstring substitution consistent with other docs.

* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
In error text return "mapvar" instead of "keymap" and "command"
instead of "function".
---
 lisp/emacs-lisp/checkdoc.el | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 5ea2f59ee6..16918746ca 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -254,7 +254,7 @@ checkdoc-ispell-lisp-words
 (defcustom checkdoc-max-keyref-before-warn nil
   "If non-nil, number of \\\\=[command-to-keystroke] tokens allowed in a doc string.
 Any more than this and a warning is generated suggesting that the construct
-\\\\={keymap} be used instead.  If the value is nil, never warn.
+\\\\={mapvar} be used instead.  If the value is nil, never warn.

 It used to not be practical to use `\\\\=[...]' very many times,
 because display of the documentation string would become slow.
@@ -1626,7 +1626,7 @@ checkdoc-this-string-valid-engine
 	     (checkdoc-create-error
 	      (concat
 	       "Keycode " (match-string 1)
-	       " embedded in doc string.  Use \\\\<keymap> & \\\\[function] "
+	       " embedded in doc string.  Use \\\\<mapvar> & \\\\[command] "
 	       "instead")
 	      (match-beginning 1) (match-end 1) t))))
      ;; Optionally warn about too many command substitutions.
@@ -1636,7 +1636,7 @@ checkdoc-this-string-valid-engine
                                      (1+ checkdoc-max-keyref-before-warn))
                   (not (re-search-forward "\\\\\\\\{\\w+}" e t)))
              (checkdoc-create-error
-              "Too many occurrences of \\[function].  Use \\{keymap} instead"
+              "Too many occurrences of \\[command].  Use \\{mapvar} instead"
               s (marker-position e)))))
      ;; Ambiguous quoted symbol.  When a symbol is both bound and fbound,
      ;; and is referred to in documentation, it should be prefixed with
--
2.32.0.windows.1

bug#50903: Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

[Eli Zaretskii]

> From: Nikolay Kudryavtsev <nikolay.kudryavtsev@gmail.com>
> Cc: 50903@debbugs.gnu.org
> Date: Thu, 30 Sep 2021 16:35:59 +0300
> 
> Roger. s/r-d the patch.

Thanks, installed.