bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

[Matthias Meulien]

[-- Attachment #1: Type: text/plain, Size: 374 bytes --]

 
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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-incomplete-keymap-description.patch --]
[-- Type: text/x-diff, Size: 3100 bytes --]

From e45b340980c9f347f4a2f0615006617bafd93260 Mon Sep 17 00:00:00 2001
From: Matthias Meulien <orontee@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


[-- Attachment #3: Type: text/plain, Size: 7075 bytes --]

 
 
 
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

bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

[Drew Adams]

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

bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

[Eli Zaretskii]

> From: Matthias Meulien <orontee@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.

bug#42325: 28.0.50; [PATCH] Incomplete keymap in Bookmark Menu mode description

[Matthias Meulien]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

Thank you.

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

> > From: Matthias Meulien <orontee@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.
>

[-- Attachment #2: Type: text/html, Size: 1128 bytes --]