bug#14199: 24.3.50; `read-kbd-macro' doc

bug#14199: 24.3.50; `read-kbd-macro' doc

[Drew Adams]

In (elisp) `Describing Characters', description of `read-kbd-macro':
 
1. The signature and description are incorrect/incomplete.  According to
the source code and the doc string, the signature is (read-kbd-macro
START &optional END).
 
The doc string shows the correct signature, and it is clearer than
the manual wrt the signature and the possibility of passing STRING
and NEED-VECTOR instead.
 
The manual needs to clearly point out that there are, in effect, two
different signatures, even if one is considered primary.  Each needs
to be documented.
 
So do not remove the existing description about STRING and NEED-VECTOR.
Instead, supplement it with a description of the other signature and its
behavior.
 
2. Mention that STRING has the form provided by `format-kbd-macro'.
`format-kbd-macro' is mentioned nowhere in the manual, and this is a
good place for it.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-09 on ODIEONE
Bzr revision: 112253 rgm@gnu.org-20130409101736-f1vzgrwt88suqqis
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

bug#14199: 24.3.50; `read-kbd-macro' doc

[Lars Ingebrigtsen]

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

> In (elisp) `Describing Characters', description of `read-kbd-macro':
>
> 1. The signature and description are incorrect/incomplete.  According to
> the source code and the doc string, the signature is (read-kbd-macro
> START &optional END).
>
> The doc string shows the correct signature, and it is clearer than
> the manual wrt the signature and the possibility of passing STRING
> and NEED-VECTOR instead.
>
> The manual needs to clearly point out that there are, in effect, two
> different signatures, even if one is considered primary.  Each needs
> to be documented.

The region-based interactive definition is documented in the Emacs
manual, while the Lisp-based is in the lispref manual.  I think that's
probably ok, while it does seem pretty strange to reuse the meanings of
the parameters.

> 2. Mention that STRING has the form provided by `format-kbd-macro'.
> `format-kbd-macro' is mentioned nowhere in the manual, and this is a
> good place for it.

Well, it mentions that it's an inverse of `key-description', which
should cover it...

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#14199: 24.3.50; `read-kbd-macro' doc

[Drew Adams]

> The region-based interactive definition is documented in the Emacs
> manual, while the Lisp-based is in the lispref manual.  I think
> that's probably ok, while it does seem pretty strange to reuse the
> meanings of the parameters.

That does not respond to the reported bug.

> > 2. Mention that STRING has the form provided by `format-kbd-
> > macro'.  `format-kbd-macro' is mentioned nowhere in the manual,
> > and this is a good place for it.
> 
> Well, it mentions that it's an inverse of `key-description', which
> should cover it...

Why close this bug without fixing it?  I gave you the info needed:
`format-kbd-macro' is precisely the thing missing - not some vague
hand-waving about an inverse of `key-description'.