GNU bug report logs - #32212
26; `subword-mode' doc string shows empty key-binding list

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Phil Sainty <psainty <at> orcon.net.nz>, Noam Postavsky <npostavs <at> gmail.com>
Cc: Stephen Berman <stephen.berman <at> gmx.net>, 32212 <at> debbugs.gnu.org, bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz <at> gnu.org>
Subject: bug#32212: 26; `subword-mode' doc string shows empty key-binding list
Date: Sun, 22 Jul 2018 18:01:54 -0700 (PDT)

> > Aha, then we should just remove it from the docstring, right?
> 
> Would it be better if the \\{some-keymap} substitution handled the
> case where there were no bindings, and printed nothing?

No.  A doc string can introduce the list of bindings any
way its author wants.  We cannot predict what text might
precede or follow the text \\{some-keymap}.

We already handle the case where the keymap is not
defined at all, by substituting this particular text:

 Uses keymap 'foo-map', which is not currently defined.

And that's not ideal either, because it, like your
suggestion (but in a different way) assumes something
about the surrounding context.

(defvar foo-map (make-keymap) "...") 
(defun foo ()
  "The key bindings are:
\\{foo-map}
For more info..."
  42)

`C-h f foo'

,----
|  foo is a Lisp function in `...'.
| 
|  (foo)
| 
|  The key bindings are:
| 
|  key             binding
|  ---             -------
| 
| 
|  For more info...
`----

(makunbound 'foo-map)
`C-h f foo'

,----
|  foo is a Lisp function in `...'.
| 
|  (foo)
| 
|  The key bindings are:
| 
| 
|  Uses keymap 'foo-map', which is not currently defined.
| 
|  For more info...
`----

With your suggestion:

,----
|  foo is a Lisp function in `...'.
| 
|  (foo)
| 
|  The key bindings are:
| 
| 
|  For more info...
`----

> That would then account for edge-cases where users add custom
> bindings to a previously-empty keymap, or clobber a populated keymap
> entirely.

I think what we have now is clearest for such cases.
It indicates that (1) the keymap is defined and (2) it
is empty - it has no defined bindings.

Printing nothing is much less clear, I think.

Arguably, the no-keymap case could be handled a bit
better.  It might not be clear to users just what "not
currently defined" is supposed to mean.  It might be
more accurate to say that the function uses `foo-map',
which is not a variable whose value is a keymap.

(Although the "currently" in the message now presumably
hints that it might become defined when a file is loaded
or some other initialization is done.  That's useful.)

Previous Next

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