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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 30 Sep 2021 11:41:46 +0300

> From: Nikolay Kudryavtsev <[email-masked]>
> 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.