bug#56816: Missing documentation of function-key-map

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 28 Jul 2022 19:30:36 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> function-key-map is not defined in the Elisp manual.
> 
> It is mentioned, in passing, on the page "Translation Keymaps" thusly:
> 
>      `local-function-key-map' inherits from `function-key-map'.  The
>      latter should only be altered if you want the binding to apply in
>      all terminals, so using the former is almost always preferred.
> 
> So, all we know about function-key-map is when to alter it (and even
> here, it is unclear what the "all" in "all terminals" means).  Not what
> it's for, not when it's looked up and used, not what its contents are.
> 
> #########################################################################
> 
> The doc string for function-key-map is a little better.  It, at least,
> attempts to give a context for the variable ("The parent keymap of all
> `local-function-key-map' instances.").
> 
> The doc string gives an example of what belongs in the variable
> ("Function key definitions that apply to all terminal devices should go
> here."), but this doesn't define its contents.  It contains more than
> function key definitions - for example, function keys with modifier keys,
> and modifier keys on their own (for example, a binding for
> event-apply-control-modifier).
> 
> These are all documentation bugs.

Would you please state clearly what exactly is a bug here?

Specifically, what is missing from the doc string of this variable?
Would saying something like "Keymap for bindings of function keys." be
enough, or is some other information missing in your opinion, and if
so, what?

Once we are done with the doc string, we can discuss whether the
manual needs any changes in this respect; in general, not every
variable must be in the manual, and as long as the doc string is
sufficient, we are fine.

Thanks.