GNU bug report logs - #17039
24.3.50; doc of `kbd`: arg format

Previous Next

Full log

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.3.50; doc of `kbd`: arg format
Date: Tue, 18 Mar 2014 19:20:44 -0700 (PDT)

1. The doc string says this:

  KEYS should be a string constant in the format used for
  saving keyboard macros (see `edmacro-mode').

That's all well and good, and it should be kept: the link provides
valuable and complete info.

However, most people consulting this doc will not be interested so much
in `edmacro-mode' or even the complete description its doc string
provides.  They will be helped most (or at least additionally) by
telling them that the format of argument KEYS is the format that `C-h k'
uses to describe a key sequence.

Please add that information, and please put it first, before adding the
`edmacro-mode' link for more complete information about the format.

2. (emacs) `Init Rebinding' at least says, in passing, that the
representation is "similar to how we have written key sequences in this
manual".

I'm not sure why it says "similar to" instead of the same as, unless
that is a reference to the fact that keys are written a bit differently
in a printed manual.  Also confusing is the fact that the manual writes
key sequences in different ways in the manual, only some of which
correspond to the syntax expected by `kbd'.  An example is given in the
same node: (global-set-key "\C-x\M-l" ...).

I don't really have a problem with what is said in that regard, though
it is not too clear.  But things would be much clearer if you would
please add that the format is what `C-h k' shows in its help.  `C-h k'
is something that even newbies learn quickly.  It gives them a point of
reference, even if it does not detail the syntax rules (as does `C-h f
edmacro-mode').

In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2014-03-10 on ODIEONE
Bzr revision: 116730 lekktu <at> gmail.com-20140311014451-rxr9uapugo5bedft
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 'CFLAGS=-O0 -g3' LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

Previous Next

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