GNU bug report logs - #50903
Checkdoc recommendation for docstring subsitutions is inconsistent with other documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50903 in the body.
You can then email your comments to 50903 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Checkdoc recommendation for docstring subsitutions is inconsistent
 with other documentation
Date: Wed, 29 Sep 2021 22:46:14 +0300

[Message part 1 (text/plain, inline)]

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.

[0001-checkdoc-Docstring-substitution-consistent-with-othe.patch (text/plain, attachment)]

Message #8 received at 50903 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
Cc: 50903 <at> debbugs.gnu.org
Subject: Re: bug#50903: Checkdoc recommendation for docstring subsitutions is
 inconsistent with other documentation
Date: Thu, 30 Sep 2021 11:41:46 +0300

> From: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> 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.

Message #11 received at 50903 <at> debbugs.gnu.org (full text, mbox):

From: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50903 <at> debbugs.gnu.org
Subject: Re: bug#50903: Checkdoc recommendation for docstring subsitutions is
 inconsistent with other documentation
Date: Thu, 30 Sep 2021 16:35:59 +0300

[Message part 1 (text/plain, inline)]

Roger. s/r-d the patch.

[0001-checkdoc-Docstring-substitution-consistent-with-othe.patch (text/plain, attachment)]

Message #16 received at 50903-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Nikolay Kudryavtsev <nikolay.kudryavtsev <at> gmail.com>
Cc: 50903-done <at> debbugs.gnu.org
Subject: Re: bug#50903: Checkdoc recommendation for docstring subsitutions is
 inconsistent with other documentation
Date: Thu, 30 Sep 2021 19:26:18 +0300

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

Thanks, installed.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.