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

Previous Next

Full log

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.

Previous Next

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