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

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Chong Yidong'" <cyd <at> gnu.org>
Cc: 9700 <at> debbugs.gnu.org
Subject: 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.