[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#50903: Checkdoc recommendation for docstring subsitutions is inconsi
From: |
Eli Zaretskii |
Subject: |
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@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.