bug#17039: 24.3.50; doc of `kbd`: arg format

bug#17039: 24.3.50; doc of `kbd`: arg format

[Drew Adams]

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@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''

bug#17039: 24.3.50; doc of `kbd`: arg format

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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