[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode desc
From: |
Drew Adams |
Subject: |
bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description |
Date: |
Sat, 11 Jul 2020 13:28:34 -0700 (PDT) |
> When one call describe-mode from *Bookmark List* buffer, the
> displayed documentation for the Bookmark Menu major mode displays
> an incomplete hard-coded keymap: The useful key /
> (bookmark-bmenu-search) isn't listed. I propose to rely on
> derived-mode-make-docstring to put the mode's keymap in mode
> docstring and to remove the currently hardcoded keymap
> description.
That's definitely a step backward, IMHO.
Just add `/' to the list.
A mode's `C-h m' documentation can, but need not,
list all of its key bindings. (It can also tell
users that they can use `C-h b'.)
But more importantly, it should describe the mode,
not just punt to say that it inherits from its
parent.
The doc of `derived-mode-make-docstring' should,
and I think does, make clear that it provides only
rudimentary, fallback help in the (hopefully rare)
case where there is no other such help.
"Construct a docstring for a new mode
if none is provided."
^^^^^^^^^^^^^^^^^^^
It doesn't say that it's a good idea to not
provide a doc string for a derived mode, and to
instead use this to construct one. Thank goodness.
Providing a doc string is normal. Not providing
one is to be avoided, and IMO, is a bug from a
user point of view.
There's little excuse for copping out and not
providing a doc string. There's even less excuse
for doing that for a mode's doc. And there's still
less excuse for _replacing_ hand-written help with
such a poor, generic, robotic fallback.
Please just do the right thing, adding the help
you think is missing. And provide whatever other
manual updates you think might help.
[To be clear, this doesn't affect me or my code.
Bookmark+ doesn't use the mode help provided by
vanilla bookmark.el. I'm just expressing my
concern for vanilla Emacs here.]