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

From: Phil Sainty <[email-masked]>
Date: Mon, 23 Jul 2018 16:15:22 +1200

On 2018-07-23 13:01, Drew Adams wrote:
>> 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}.

Ah, yes, agreed -- a search shows quite a variety of such introductory
phrases:

"The following key bindings are currently in effect in the buffer:"
"Customized bindings may be defined in `ielm-map', which currently 
contains:"
"The following commands are available:"
"In addition to Emacs-Lisp Mode, the following commands are available:"
"Keys specific to Follow mode:"
"Instead these commands are provided:"
"In the browser, use the following keys:"
"Key bindings:"
"Special commands:"
"The keymap for this second window is:"
"Commands:"
"Tree mode key bindings:"
"Key definitions:"
"Commands:"
"Here are all keybindings."
etc, etc...

I think there's a lot of unnecessary inconsistency here which would
probably benefit from a common phrasing.  That could feasibly be
provided via an alternative variant of the \\{...} syntax (at which
point it could make more sense to include some automated variations
for edge cases), but that all sounds like more trouble than it's
worth, so I'm not really suggesting that this should be done (even
if it strikes me as a "nice to have").

-Phil