GNU bug report logs - #9700
24.0.50; doc string of `key-description'

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 9700 in the body.
You can then email your comments to 9700 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.0.50; doc string of `key-description'
Date: Fri, 7 Oct 2011 23:46:14 -0700

The doc string dates from before Emacs 21.  It was correct then but has
been incorrect ever since the nutty decision in Emacs 21 to add angle
brackets around function keys.
 
emacs -Q
 
(setq toto  (read-key-sequence "k: "))
 
Hold the Control key and hit the Insert key.
 
(key-description toto) => "<C-insert>"
 
From the doc string:
 
 "Control characters turn into "C-foo" sequences, meta into "M-foo",
  spaces are put between sequence elements, etc."
 
Since Emacs 21 that needs to be changed to "<C-foo>" and "<M-foo>",
since "foo" is obviously the name of a function key (more than one
character in the name).
 
And of course it would be better not to use "foo" at all, but to use an
example like that in the Elisp manual: (elisp) `Describing Characters'
is accurate.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-09-19 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'
 

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

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 9700 <at> debbugs.gnu.org
Subject: Re: bug#9700: 24.0.50; doc string of `key-description'
Date: Mon, 12 Mar 2012 01:09:12 +0800

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

>  "Control characters turn into "C-foo" sequences, meta into "M-foo",
>   spaces are put between sequence elements, etc."
>  
> Since Emacs 21 that needs to be changed to "<C-foo>" and "<M-foo>",
> since "foo" is obviously the name of a function key (more than one
> character in the name).

No, these are not referring to function keys.  I tweaked the docstring
to make this clearer.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>
Cc: 9700 <at> debbugs.gnu.org
Subject: RE: bug#9700: 24.0.50; doc string of `key-description'
Date: Sun, 11 Mar 2012 10:57:49 -0700

> >  "Control characters turn into "C-foo" sequences, meta into "M-foo",
> >   spaces are put between sequence elements, etc."
> >  
> > Since Emacs 21 that needs to be changed to "<C-foo>" and "<M-foo>",
> > since "foo" is obviously the name of a function key (more than one
> > character in the name).
> 
> No, these are not referring to function keys.  I tweaked the docstring
> to make this clearer.

I have not seen your fix yet. b Bt clearly as they were written they did refer
to function keys (no spaces: `f o o').

As far as control and meta are concerned, it would be clear enough if you wrote
just "C-" and "M-".  Dunno if that's what you did.

However, it is not enough to mention that control goes to `C-', meta to `M-',
and spaces are used as separators - and then end with "etc."  That is far too
incomplete.

A more complete description should be given explicitly (including handling of
function keys with angle brackets).

Or (preferably) it should (after the "etc.") just do what the doc for `kbd'
does.  It can simply state that the return value is a value that would be
acceptable to `kbd'.  Or it can repeat what the `kbd' doc string says: "the
format used for saving keyboard macros (see `edmacro-mode')."

The point is that `key-description' needs to clearly let users know about the
format of the returned description, one way or another.  It is not acceptable to
punt with "etc.".

Previous Next

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