GNU bug report logs - #27490
24.5; Elisp manual explanation of `function-key-map' and its inheritors

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 27490 in the body.
You can then email your comments to 27490 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; Elisp manual explanation of `function-key-map' and its
 inheritors
Date: Sun, 25 Jun 2017 13:33:03 -0700 (PDT)

Nothing is said about `function-key-map' and its inheritance relations,
beyond the fact that local such maps inherit from `f-k-m', and that
`f-k-m' "should not be used directly" (no reason given).

Please consider explaining `function-key-map'.

In http://lists.gnu.org/archive/html/emacs-devel/2017-06/msg00595.html,
for example, Stefan counsels to "just use function-key-map to translate
[touch-event] to []".  It's not clear how a reader of the manual would
come to such an understanding.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

Message #8 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 27490 <at> debbugs.gnu.org
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Sun, 21 Jul 2019 17:33:45 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Nothing is said about `function-key-map' and its inheritance relations,
> beyond the fact that local such maps inherit from `f-k-m', and that
> `f-k-m' "should not be used directly" (no reason given).
>
> Please consider explaining `function-key-map'.

This text:

------

@code{local-function-key-map} inherits from @code{function-key-map},
but the latter should not be used directly.

------

was added by this commit:

------

commit 6b9e769476955b928b0248fef5aaa0e40754e257
Author: Eli Zaretskii <eliz <at> gnu.org>
Date:   Sat Jan 17 19:14:52 2009 +0000

    (Translation Keymaps): Rename function-key-map to local-function-key-map.

------


So I'm assuming that there was a plan to phase out using
function-key-map or something?  Perhaps Eli can clarify.

But there's a bunch of examples in the manual that does use the map, so
either these should be adjusted, or the documentation clarified:

------

The only way to affect the behavior of keys within Emacs is through
@code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs).  The
@code{define-key} command should be used in conjunction with the
@code{function-key-map} map.  For instance,

@lisp
(define-key function-key-map [M-@key{TAB}] [?\M-\t])
@end lisp

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #11 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5;
 Elisp manual explanation of `function-key-map' and its inheritors
Date: Sun, 21 Jul 2019 19:39:49 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Sun, 21 Jul 2019 17:33:45 +0200
> Cc: 27490 <at> debbugs.gnu.org
> 
> This text:
> 
> ------
> 
> @code{local-function-key-map} inherits from @code{function-key-map},
> but the latter should not be used directly.
> 
> ------
> 
> was added by this commit:
> 
> ------
> 
> commit 6b9e769476955b928b0248fef5aaa0e40754e257
> Author: Eli Zaretskii <eliz <at> gnu.org>
> Date:   Sat Jan 17 19:14:52 2009 +0000
> 
>     (Translation Keymaps): Rename function-key-map to local-function-key-map.
> 
> ------
> 
> 
> So I'm assuming that there was a plan to phase out using
> function-key-map or something?  Perhaps Eli can clarify.

I don't remember any details, and I found no discussions of this
around that date.  However, you will find a bunch of commits around
that one which all renamed function-key-map to
local-function-key-map.  So yes, it appears like we wanted people to
use the latter.

> But there's a bunch of examples in the manual that does use the map, so
> either these should be adjusted, or the documentation clarified:

I think the examples which use function-key-map should be modified,
yes.

> The only way to affect the behavior of keys within Emacs is through
> @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs).  The
> @code{define-key} command should be used in conjunction with the
> @code{function-key-map} map.  For instance,
> 
> @lisp
> (define-key function-key-map [M-@key{TAB}] [?\M-\t])
> @end lisp

Where did you find this?  I must be blind, because I don't see this
passage in the manual.

Message #14 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Sun, 21 Jul 2019 19:31:45 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> The only way to affect the behavior of keys within Emacs is through
>> @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs).  The
>> @code{define-key} command should be used in conjunction with the
>> @code{function-key-map} map.  For instance,
>> 
>> @lisp
>> (define-key function-key-map [M-@key{TAB}] [?\M-\t])
>> @end lisp
>
> Where did you find this?  I must be blind, because I don't see this
> passage in the manual.

It's in the "X key translations for Emacs" node in misc/efaq.texi, which
I guess isn't part of the manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #17 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Sun, 21 Jul 2019 20:54:11 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: drew.adams <at> oracle.com,  27490 <at> debbugs.gnu.org
> Date: Sun, 21 Jul 2019 19:31:45 +0200
> 
> >> The only way to affect the behavior of keys within Emacs is through
> >> @code{xmodmap} (outside Emacs) or @code{define-key} (inside Emacs).  The
> >> @code{define-key} command should be used in conjunction with the
> >> @code{function-key-map} map.  For instance,
> >> 
> >> @lisp
> >> (define-key function-key-map [M-@key{TAB}] [?\M-\t])
> >> @end lisp
> >
> > Where did you find this?  I must be blind, because I don't see this
> > passage in the manual.
> 
> It's in the "X key translations for Emacs" node in misc/efaq.texi, which
> I guess isn't part of the manual.

Ah, okay.  Yes, that part of the FAQ is obsolete and should be fixed.

Message #20 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Sun, 21 Jul 2019 20:16:31 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> It's in the "X key translations for Emacs" node in misc/efaq.texi, which
>> I guess isn't part of the manual.
>
> Ah, okay.  Yes, that part of the FAQ is obsolete and should be fixed.

Would `local-function-key-map' be the right things to replace it with in
these examples?  (There's one in the viper manual, too.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #23 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Tue, 23 Jul 2019 17:58:23 +0300

> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Cc: drew.adams <at> oracle.com,  27490 <at> debbugs.gnu.org
> Date: Sun, 21 Jul 2019 20:16:31 +0200
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> It's in the "X key translations for Emacs" node in misc/efaq.texi, which
> >> I guess isn't part of the manual.
> >
> > Ah, okay.  Yes, that part of the FAQ is obsolete and should be fixed.
> 
> Would `local-function-key-map' be the right things to replace it with in
> these examples?  (There's one in the viper manual, too.)

Yes, I think so.

Message #26 received at 27490 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 27490 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#27490: 24.5; Elisp manual explanation of `function-key-map'
 and its inheritors
Date: Tue, 23 Jul 2019 19:16:13 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Would `local-function-key-map' be the right things to replace it with in
>> these examples?  (There's one in the viper manual, too.)
>
> Yes, I think so.

OK; I've now adjusted these instances (and two in the Emacs user manual,
too).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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