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/