GNU bug report logs - #14199
24.3.50; `read-kbd-macro' doc

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 14199 in the body.
You can then email your comments to 14199 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; `read-kbd-macro' doc
Date: Sat, 13 Apr 2013 10:49:04 -0700

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

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 14199 <at> debbugs.gnu.org
Subject: Re: bug#14199: 24.3.50; `read-kbd-macro' doc
Date: Sat, 08 Feb 2014 04:33:02 -0800

"Drew Adams" <drew.adams <at> 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/

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 14199 <at> debbugs.gnu.org
Subject: RE: bug#14199: 24.3.50; `read-kbd-macro' doc
Date: Mon, 10 Feb 2014 14:00:44 -0800 (PST)

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

Previous Next

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