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

[Drew Adams]

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