all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#56816: Missing documentation of function-key-map
@ 2022-07-28 19:30 Alan Mackenzie
  2022-07-29  7:19 ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Alan Mackenzie @ 2022-07-28 19:30 UTC (permalink / raw)
  To: 56816

Hello, Emacs.

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.

-- 
Alan Mackenzie (Nuremberg, Germany).





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-28 19:30 bug#56816: Missing documentation of function-key-map Alan Mackenzie
@ 2022-07-29  7:19 ` Eli Zaretskii
  2022-07-29 19:50   ` Alan Mackenzie
  0 siblings, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-07-29  7:19 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: 56816

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





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-29  7:19 ` Eli Zaretskii
@ 2022-07-29 19:50   ` Alan Mackenzie
  2022-07-29 19:55     ` Gregory Heytings
  2022-07-30  6:42     ` Eli Zaretskii
  0 siblings, 2 replies; 8+ messages in thread
From: Alan Mackenzie @ 2022-07-29 19:50 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 56816, acm

Hello, Eli.

On Fri, Jul 29, 2022 at 10:19:59 +0300, Eli Zaretskii wrote:
> > 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?

That there is a reference to function-key-map in that manual page, but
there is no description of function-key-map whatsoever in the manual.  If
things are to stay that way, perhaps we could add something like "(not
documented in this manual.  See the variable's doc string for details.)"
as a footnote. 

> 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?

That description would be a big improvement.  Perhaps it could also say
"including modifiers for some keys" or something like that; The
modifiers, all 7 combinations, are included for each keypad key, but not
for the other function keys.

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

I'll tell you what gave rise to this.  On a proprietary system in my day
job, typing C-M-a is giving the result M-á, and similarly for the other
four vowels with C-M-.  This should be relatively straightforward to
remedy, but I've been struggling with that manual page for two evenings,
now.  The manual page ("Translation Keymaps") seems to have most of the
information, but there is little clarity and little redundancy.  I think
I need to add a binding for M-á to convert it to C-M-a, but in which
keymap?  There are three keymaps described on the page, but their
purposes are not entirely clear.  One of them is the one I need, I think.

It surely shouldn't take several hours to digest the information on a
single moderately sized info page.

> Thanks.

-- 
Alan Mackenzie (Nuremberg, Germany).





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-29 19:50   ` Alan Mackenzie
@ 2022-07-29 19:55     ` Gregory Heytings
  2022-07-29 20:44       ` Alan Mackenzie
  2022-07-30  6:42     ` Eli Zaretskii
  1 sibling, 1 reply; 8+ messages in thread
From: Gregory Heytings @ 2022-07-29 19:55 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: 56816, Eli Zaretskii


>
> there is no description of function-key-map whatsoever in the manual.
>

M-: (info "(elisp) Standard Keymaps") RET C-s fun RET





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-29 19:55     ` Gregory Heytings
@ 2022-07-29 20:44       ` Alan Mackenzie
  2022-07-30  6:43         ` Eli Zaretskii
  0 siblings, 1 reply; 8+ messages in thread
From: Alan Mackenzie @ 2022-07-29 20:44 UTC (permalink / raw)
  To: Gregory Heytings; +Cc: 56816, Eli Zaretskii

Hello, Gregory.

On Fri, Jul 29, 2022 at 19:55:43 +0000, Gregory Heytings wrote:

> > there is no description of function-key-map whatsoever in the manual.

> M-: (info "(elisp) Standard Keymaps") RET C-s fun RET

Thanks!  I ought to have just said there is no index entry for
function-key-map.

Even then, the description on "Standard Keymaps" is not good.  Rather
than saying what function-key-map _is_, it merely describes its
relationship to some other keymaps.

-- 
Alan Mackenzie (Nuremberg, Germany).





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-29 19:50   ` Alan Mackenzie
  2022-07-29 19:55     ` Gregory Heytings
@ 2022-07-30  6:42     ` Eli Zaretskii
  2022-07-30 15:29       ` Drew Adams
  1 sibling, 1 reply; 8+ messages in thread
From: Eli Zaretskii @ 2022-07-30  6:42 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: 56816

> Date: Fri, 29 Jul 2022 19:50:35 +0000
> Cc: 56816@debbugs.gnu.org, acm@muc.de
> From: Alan Mackenzie <acm@muc.de>
> 
> > > These are all documentation bugs.
> 
> > Would you please state clearly what exactly is a bug here?
> 
> That there is a reference to function-key-map in that manual page, but
> there is no description of function-key-map whatsoever in the manual.  If
> things are to stay that way, perhaps we could add something like "(not
> documented in this manual.  See the variable's doc string for details.)"
> as a footnote. 

The real description is in "Translation Keymaps" (where you get by
following the cross-reference near local-function-key-map, which
itself is referenced from function-key-map).  I've now added an index
entry for function-key-map in "Translation Keymaps".

> > 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?
> 
> That description would be a big improvement.  Perhaps it could also say
> "including modifiers for some keys" or something like that; The
> modifiers, all 7 combinations, are included for each keypad key, but not
> for the other function keys.

The doc string includes a link top local-function-key-map, whose doc
string describes some more.

Given all of the above, what else is missing?  Please be specific.

> > 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.
> 
> I'll tell you what gave rise to this.  On a proprietary system in my day
> job, typing C-M-a is giving the result M-á, and similarly for the other
> four vowels with C-M-.  This should be relatively straightforward to
> remedy, but I've been struggling with that manual page for two evenings,
> now.  The manual page ("Translation Keymaps") seems to have most of the
> information, but there is little clarity and little redundancy.  I think
> I need to add a binding for M-á to convert it to C-M-a, but in which
> keymap?  There are three keymaps described on the page, but their
> purposes are not entirely clear.  One of them is the one I need, I think.

This doesn't really help, because I don't see how what you describe is
related to the stuff that is or isn't in the documentation.  I'm not
even sure I understand why you think function-key-map is what you need
to investigate, and how are your needs related to what, if anything,
is wrong with or missing from the material in "Translation Keymaps".
"Little clarity and little redundancy" doesn't help me understand what
needs to be done.





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-29 20:44       ` Alan Mackenzie
@ 2022-07-30  6:43         ` Eli Zaretskii
  0 siblings, 0 replies; 8+ messages in thread
From: Eli Zaretskii @ 2022-07-30  6:43 UTC (permalink / raw)
  To: Alan Mackenzie; +Cc: 56816, gregory

> Date: Fri, 29 Jul 2022 20:44:17 +0000
> Cc: Eli Zaretskii <eliz@gnu.org>, 56816@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > M-: (info "(elisp) Standard Keymaps") RET C-s fun RET
> 
> Thanks!  I ought to have just said there is no index entry for
> function-key-map.

That is now fixed.

> Even then, the description on "Standard Keymaps" is not good.  Rather
> than saying what function-key-map _is_, it merely describes its
> relationship to some other keymaps.

That node is just a list, the real description is in the places to
which you get by following the cross-references.





^ permalink raw reply	[flat|nested] 8+ messages in thread

* bug#56816: Missing documentation of function-key-map
  2022-07-30  6:42     ` Eli Zaretskii
@ 2022-07-30 15:29       ` Drew Adams
  0 siblings, 0 replies; 8+ messages in thread
From: Drew Adams @ 2022-07-30 15:29 UTC (permalink / raw)
  To: Eli Zaretskii, Alan Mackenzie; +Cc: 56816@debbugs.gnu.org

> I've now added an index entry for
> function-key-map in "Translation Keymaps".

+1





^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2022-07-30 15:29 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-07-28 19:30 bug#56816: Missing documentation of function-key-map Alan Mackenzie
2022-07-29  7:19 ` Eli Zaretskii
2022-07-29 19:50   ` Alan Mackenzie
2022-07-29 19:55     ` Gregory Heytings
2022-07-29 20:44       ` Alan Mackenzie
2022-07-30  6:43         ` Eli Zaretskii
2022-07-30  6:42     ` Eli Zaretskii
2022-07-30 15:29       ` Drew Adams

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.