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

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 17039 in the body.
You can then email your comments to 17039 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.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''

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 17039 <at> debbugs.gnu.org
Subject: Re: bug#17039: 24.3.50; doc of `kbd`: arg format
Date: Fri, 29 Apr 2016 20:27:32 +0200

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

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

I've now done this.

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