GNU bug report logs - #42325
28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

Previous Next

Full log

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Matthias Meulien <orontee <at> gmail.com>, 42325 <at> debbugs.gnu.org
Subject: RE: 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.]

Previous Next

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