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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 42325 in the body.
You can then email your comments to 42325 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Matthias Meulien <orontee <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description
Date: Sat, 11 Jul 2020 21:15:57 +0200

[Message part 1 (text/plain, inline)]

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.

[0001-Fix-incomplete-keymap-description.patch (text/x-diff, inline)]

From e45b340980c9f347f4a2f0615006617bafd93260 Mon Sep 17 00:00:00 2001
From: Matthias Meulien <orontee <at> gmail.com>
Date: Sat, 11 Jul 2020 20:55:59 +0200
Subject: [PATCH] Fix incomplete keymap description

* lisp/bookmark.el (bookmark-bmenu-mode):
  Rely on derived-mode-make-docstring to put the mode's keymap in mode
  docstring
---
 lisp/bookmark.el | 31 +------------------------------
 1 file changed, 1 insertion(+), 30 deletions(-)

diff --git a/lisp/bookmark.el b/lisp/bookmark.el
index 5bb1698171..cf8d6e3241 100644
--- a/lisp/bookmark.el
+++ b/lisp/bookmark.el
@@ -1745,36 +1745,7 @@ bookmark-bmenu-mode
   "Major mode for editing a list of bookmarks.
 Each line describes one of the bookmarks in Emacs.
 Letters do not insert themselves; instead, they are commands.
-Bookmark names preceded by a \"*\" have annotations.
-\\<bookmark-bmenu-mode-map>
-\\[bookmark-bmenu-mark] -- mark bookmark to be displayed.
-\\[bookmark-bmenu-select] -- select bookmark of line point is on.
-  Also show bookmarks marked using m in other windows.
-\\[bookmark-bmenu-toggle-filenames] -- toggle displaying of filenames (they may obscure long bookmark names).
-\\[bookmark-bmenu-locate] -- display (in minibuffer) location of this bookmark.
-\\[bookmark-bmenu-1-window] -- select this bookmark in full-frame window.
-\\[bookmark-bmenu-2-window] -- select this bookmark in one window,
-  together with bookmark selected before this one in another window.
-\\[bookmark-bmenu-this-window] -- select this bookmark in place of the bookmark menu buffer.
-\\[bookmark-bmenu-other-window] -- select this bookmark in another window,
-  so the bookmark menu bookmark remains visible in its window.
-\\[bookmark-bmenu-other-frame] -- select this bookmark in another frame.
-\\[bookmark-bmenu-switch-other-window] -- switch the other window to this bookmark.
-\\[bookmark-bmenu-rename] -- rename this bookmark (prompts for new name).
-\\[bookmark-bmenu-relocate] -- relocate this bookmark's file (prompts for new file).
-\\[bookmark-bmenu-delete] -- mark this bookmark to be deleted, and move down.
-\\[bookmark-bmenu-delete-backwards] -- mark this bookmark to be deleted, and move up.
-\\[bookmark-bmenu-execute-deletions] -- delete bookmarks marked with `\\[bookmark-bmenu-delete]'.
-\\[bookmark-bmenu-save] -- save the current bookmark list in the default file.
-  With a prefix arg, prompts for a file to save in.
-\\[bookmark-bmenu-load] -- load in a file of bookmarks (prompts for file.)
-\\[bookmark-bmenu-unmark] -- remove all kinds of marks from current line.
-  With prefix argument, also move up one line.
-\\[bookmark-bmenu-backup-unmark] -- back up a line and remove marks.
-\\[bookmark-bmenu-show-annotation] -- show the annotation, if it exists, for the current bookmark
-  in another buffer.
-\\[bookmark-bmenu-show-all-annotations] -- show the annotations of all bookmarks in another buffer.
-\\[bookmark-bmenu-edit-annotation] -- edit the annotation for the current bookmark."
+Bookmark names preceded by a \"*\" have annotations."
   (setq truncate-lines t)
   (setq buffer-read-only t))
 
-- 
2.20.1

[Message part 3 (text/plain, inline)]

In GNU Emacs 28.0.50 (build 22, x86_64-pc-linux-gnu, GTK+ Version 
3.24.5, cairo version 1.16.0) 
of 2020-06-30 built on carbon 
Repository revision: bc8089a3fa11161428c51439fd3b26fd6583345d 
Repository branch: master Windowing system distributor 'The X.Org 
Foundation', version 11.0.12004000 System Description: Debian 
GNU/Linux 10 (buster)  Recent messages: mouse-2, RET: find 
function's definition uncompressing emacsbug.el.gz...done Note: 
file is write protected Mark set Mark saved where search started 
Mark set scroll-down-command: Beginning of buffer [8 times] Quit 
Type "q" in help window to restore its previous buffer.  Finding 
changes in ~/Sources/emacs/...   Configured features: XPM JPEG 
TIFF GIF PNG RSVG CAIRO SOUND GPM DBUS GSETTINGS GLIB NOTIFY 
INOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE HARFBUZZ M17N_FLT 
LIBOTF ZLIB TOOLKIT_SCROLL_BARS GTK3 X11 XDBE XIM MODULES THREADS 
JSON PDUMPER LCMS2 GMP Important settings: 
 value of $LC_MONETARY: fr_FR.UTF-8 value of $LC_NUMERIC: 
 fr_FR.UTF-8 value of $LC_TIME: fr_FR.UTF-8 value of $LANG: 
 fr_FR.UTF-8 value of $XMODIFIERS: @im=ibus locale-coding-system: 
 utf-8-unix 

Major mode: VC dir  Minor modes in effect: 
 semantic-minor-modes-format: ((:eval (if (or 
 semantic-highlight-edits-mode 
 semantic-show-unmatched-syntax-mode semantic-idle-scheduler-mode 
 semantic-mru-bookmark-mode)  S))) vc-parent-buffer: 
 *vc-dir*<emacs> highlight-changes-visible-mode: t 
 show-paren-mode: t shell-dirtrack-mode: t minions-mode: t 
 semantic-mode: t desktop-save-mode: t save-place-mode: t 
 electric-pair-mode: t icomplete-mode: t global-so-long-mode: t 
 global-auto-revert-mode: t auto-insert-mode: t text-scale-mode: 
 t tooltip-mode: t global-eldoc-mode: t electric-layout-mode: t 
 electric-indent-mode: t mouse-wheel-mode: t tab-bar-mode: t 
 file-name-shadow-mode: t global-font-lock-mode: t 
 font-lock-mode: t blink-cursor-mode: t window-divider-mode: t 
 auto-composition-mode: t auto-encryption-mode: t 
 auto-compression-mode: t buffer-read-only: t line-number-mode: t 
 transient-mark-mode: t 

Load-path shadows: None found.   Features: (shadow emacsbug 
sendmail log-view log-edit pcvs-util add-log eieio-opt speedbar 
dframe help-fns radix-tree smerge-mode diff dabbrev tramp-cache 
hl-line calc-map calc-stat calc-vec calc-ext misearch 
multi-isearch mule-util calc-menu calc-aent calc calc-loaddefs 
calc-macs flow-fill etags fileloop sort gnus-cite smiley shr-color 
color mm-archive mail-extr gnus-async gnus-bcklg qp gnus-ml 
disp-table gnus-topic nndraft nnmh nnfolder utf-7 epa-file gnutls 
network-stream nsm gnus-agent gnus-srvr gnus-score score-mode 
nnvirtual gnus-msg gnus-art mm-uu mml2015 mm-view mml-smime smime 
dig gnus-cache whitespace sh-script smie executable rst generic 
bug-reference flyspell ox-odt rng-loc rng-uri rng-parse rng-match 
rng-dt rng-util rng-pttrn nxml-parse nxml-ns nxml-enc xmltok 
nxml-util ox-latex ox-icalendar ox-html table ox-ascii ox-publish 
ox goto-addr org-element avl-tree generator ol-eww ol-rmail ol-mhe 
ol-irc ol-info ol-gnus nnir gnus-sum url url-proxy url-privacy 
url-expand url-methods url-history mailcap shr url-cookie 
url-domsuf svg xml dom ol-docview doc-view jka-compr image-mode 
exif ol-bibtex bibtex ol-bbdb ol-w3m semantic/wisent/python 
semantic/wisent/python-wy semantic/wisent semantic/wisent/wisent 
rx vc-mtn vc-hg vc-bzr vc-src vc-sccs vc-svn vc-cvs vc-rcs eglot 
array jsonrpc ert debug backtrace xref flymake-proc flymake 
thingatpt warnings compile pcase url-util project imenu python 
tramp-sh tramp tramp-loaddefs trampver tramp-integration files-x 
tramp-compat ls-lisp conf-mode semantic/bovine/make 
semantic/decorate/include semantic/db-find semantic/db-ref 
semantic/decorate/mode semantic/decorate pulse semantic/dep 
semantic/bovine/make-by semantic/bovine display-line-numbers 
hilit-chg make-mode yasnippet-snippets yasnippet dired-aux paren 
vc-dir ewoc vc vc-dispatcher bash-completion shell cl-extra 
help-mode avoid minions carbon-custom cus-edit cus-start cus-load 
gnus-demon nntp gnus-group gnus-undo gnus-start gnus-cloud nnimap 
nnmail mail-source utf7 netrc parse-time iso8601 gnus-spec 
gnus-win nnoo gnus-int gnus-range message rmc puny rfc822 mml 
mml-sec epa derived epg epg-config mm-decode mm-bodies mm-encode 
mail-parse rfc2231 mailabbrev gmm-utils mailheader gnus nnheader 
gnus-util rmail rmail-loaddefs rfc2047 rfc2045 ietf-drums 
mail-utils mm-util mail-prsvr wid-edit gnus-dired dired-x dired 
dired-loaddefs org-capture org ob ob-tangle ob-ref ob-lob ob-table 
ob-exp org-macro org-footnote org-src ob-comint org-pcomplete 
pcomplete comint ansi-color org-list org-faces org-entities 
time-date noutline outline org-version ob-emacs-lisp ob-core 
ob-eval org-table ol org-keys org-compat org-macs org-loaddefs 
format-spec cal-menu calendar cal-loaddefs advice skeleton 
find-file vc-git diff-mode easy-mmode semantic/mru-bookmark ring 
semantic/db-mode semantic/idle semantic/analyze semantic/sort 
semantic/scope semantic/analyze/fcn semantic/db eieio-base 
semantic/format ezimage semantic/tag-ls semantic/find 
semantic/ctxt semantic/util-modes semantic/util semantic 
semantic/tag semantic/lex semantic/fw mode-local find-func cedet 
ispell desktop frameset server bookmark text-property-search pp 
saveplace elec-pair edmacro kmacro icomplete so-long autorevert 
filenotify autoinsert cc-mode cc-fonts cc-guess cc-menus cc-cmds 
cc-styles cc-align cc-engine cc-vars cc-defs generic-x face-remap 
proof-site proof-autoloads info package easymenu browse-url 
url-handlers url-parse auth-source cl-seq eieio eieio-core cl-macs 
eieio-loaddefs password-cache json subr-x map url-vars seq 
byte-opt gv bytecomp byte-compile cconv cl-loaddefs cl-lib tooltip 
eldoc electric uniquify ediff-hook vc-hooks lisp-float-type mwheel 
term/x-win x-win term/common-win x-dnd tool-bar dnd fontset image 
regexp-opt fringe tabulated-list replace newcomment text-mode 
elisp-mode lisp-mode prog-mode register page tab-bar menu-bar 
rfn-eshadow isearch timer select scroll-bar mouse jit-lock 
font-lock syntax facemenu font-core term/tty-colors frame 
minibuffer cl-generic cham georgian utf-8-lang misc-lang 
vietnamese tibetan thai tai-viet lao korean japanese eucjp-ms 
cp51932 hebrew greek romanian slovak czech european ethiopic 
indian cyrillic chinese composite charscript charprop case-table 
epa-hook jka-cmpr-hook help simple abbrev obarray cl-preloaded 
nadvice loaddefs button faces cus-face macroexp files 
text-properties overlay sha1 md5 base64 format env code-pages mule 
custom widget hashtable-print-readable backquote threads dbusbind 
inotify lcms2 dynamic-setting system-font-setting 
font-render-setting cairo move-toolbar gtk x-toolkit x multi-tty 
make-network-process emacs)  Memory information: ((conses 16 
716231 86353) 
(symbols 48 44640 61) (strings 32 173896 12445) (string-bytes 1 
6166036) (vectors 16 75398) (vector-slots 8 1825868 200660) 
(floats 8 485 330) (intervals 56 25773 1448) (buffers 992 162)) 

-- 
Matthias

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.]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Matthias Meulien <orontee <at> gmail.com>
Cc: 42325-done <at> debbugs.gnu.org
Subject: Re: bug#42325: 28.0.50;
 [PATCH] Incomplete keymap in Bookmark Menu mode description
Date: Sat, 18 Jul 2020 10:55:05 +0300

> From: Matthias Meulien <orontee <at> gmail.com>
> Date: Sat, 11 Jul 2020 21:15:57 +0200
> 
> 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.

Thanks.

As Drew points out, there's no need to show the entire set of
commands, so I just added '/' to the list.

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

From: Matthias Meulien <orontee <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 42325-done <at> debbugs.gnu.org
Subject: Re: bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu
 mode description
Date: Sat, 18 Jul 2020 11:59:10 +0200

[Message part 1 (text/plain, inline)]

Thank you.

Le sam. 18 juil. 2020 09:55, Eli Zaretskii <eliz <at> gnu.org> a écrit :

> > From: Matthias Meulien <orontee <at> gmail.com>
> > Date: Sat, 11 Jul 2020 21:15:57 +0200
> >
> > 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.
>
> Thanks.
>
> As Drew points out, there's no need to show the entire set of
> commands, so I just added '/' to the list.
>

[Message part 2 (text/html, inline)]

Previous Next

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