RE: address@hidden: bug in read-kbd-macro

[Drew Adams]

    > The first question is whether this is a bug: should (read-kbd-macro
    > "mode-line" t) return [mode-line]?

    I don't think so; as the lispref documentation for read-kbd-macro
    says, it is roughly an inverse of `key-description', and

     M-: (key-description [mode-line]) RET ==> "<mode-line>"

    > To complicate things, I see that (read-kbd-macro "<mode-line>"),
    > with or without the second arg, returns [mode-line].

    This is correct.

Yes, I already said that that part was correct. The problem is for
unbracketed descriptions, as I indicated.

    I think we should close this bug.

I disagree, on two counts -

1. There was also a suggestion in the bug report to improve the doc string
of `read-kbd-macro'. The description of the arguments in the two cases of
interactive and Lisp use is confusing. This is independent of the rest of
the bug report.

2. The bug reported is not about the behavior when angle brackets are
included. There is no bug in that case, as I stated, so there is no sense
citing that case as evidence that there is no bug. The bug is about the
behavior when angle brackets are not used in the key description. Key
descriptions need not have angle brackets, and `read-kbd-macro' should
handle that case also.

(And, yes, read-kbd-macro should be an inverse of key-description.)

Angle-bracket notation is, at least in some contexts, highly UNreadable. I
gave two examples showing why angle brackets can be unhelpful. One was
simply the different treatment of `C-d' and `<C-left>', which users don't
think of as being significantly different types of critter (Occam's razor).
A UI that refers to them both without angle brackets is more readable in
many contexts. The other example concerned the sort order of key names,
which is thrown off by `>', so, for instance, `<C-M-down-mouse-1>' appears
before, not after, `<C-M-down>' alphabetically.

The larger point is that applications should be able to use either external
key-description notation (with or without <>) easily - the Lisp functions
that produce and consume such descriptions shouldn't make it hard to use
either notation.

It's very good that we have a `no-angle' option to `single-key-description'.
What's needed, I think, is a `no-angle' option for `key-description' and
`read-kbd-macro' also, so users can control the external key representation
format to be used (bracketed or not). Then, we would have the following
(only the * are new):

*1. (key-description [mode-line] 'no-angles) => "mode-line"
 2. (single-key-description 'mode-line 'no-angles) => "mode-line"
*3. (read-kbd-macro "mode-line" t 'no-angles) => [mode-line]

 4. (key-description [mode-line]) => "<mode-line>"
 5. (single-key-description 'mode-line) => "<mode-line>"
 6. (read-kbd-macro "<mode-line>" t) => [mode-line]

We already have everything except #1 and #3. In Emacs 20, we already had the
result of #1, but for #4, so #1 must be feasible to implement.

---

BTW, some other problems with key notation -

1. The Emacs manual does not use the notation <next>; it uses <NEXT>. Is
this the right thing? The Lisp functions that provide key descriptions
produce <next>, not <NEXT>.

2. The Emacs manual's treatment of <NEXT>, <F10>, etc. is on a par with its
treatment of <CTRL>, <META>, <ALT>, and <SHIFT>, which I don't think are
possible outputs of the key-description functions, not being complete keys.

I wonder what the manual convention is, and whether it needs to fit what the
key-description functions return. Shouldn't we distinguish things such as
<META> from things such as <next>?

3. I personally think `next' and `f10' are clearer than <NEXT> and <F10>,
and they are more consistent with, say, `C-x' and `b'. The only possible
confusion is between a multiple-key sequence such as `f 10' or `f 1 0'
(assuming `f' and `f 1' are prefix keys) and a key sequence such as `f10',
and I think we already have the convention of using spaces to distinguish
these.

Do we have any key names that contain spaces, so that angle-bracket notation
would actually add something important? I don't know of any. If we did,
then, yes, `<foo bar> 5' is unambiguous, whereas `foo bar 5' could be
ambiguous. In that case alone, we might use brackets.

4. If we do change the manual convention along the lines I suggest, we might
want to reconsider things like <SPC> (which would become `SPC' by my
suggestion) and <RET>. Is there any good reason for these to be uppercase?
How about just `spc' and `ret' (and `tab' etc.)?

5. I note too that `describe-key' shows SPC, RET, and DEL, not <SPC>, <RET>,
and <DEL>, in *Help*. And keystroke echoing shows ESC, not <ESC>. These
usages are thus also inconsistent with what is in the Emacs manual (<SPC>,
<RET>, and <DEL>).

6. The manual writes `M-<RET>', not <M-RET> - 1) quotes are used, in
addition to angle brackets; and 2) the angle brackets don't surround the
modifier. As someone else recently pointed out, the angle-bracket notation
used by the key-description functions puts the modifier inside the brackets
(e.g. <S-tab>). So, here is another inconsistency between the manual and the
description functions. (I imagine that the quotes were added because of the
presence of the modifier.)

I tend to agree with the other writer, BTW, that S-<tab> is more readable
than <S-tab>, but we should at least be consistent. Again, to me, the most
readable is `S-tab' (or S-tab, in some contexts); the angle brackets add
nothing but noise, wherever they are placed.

7. Is it correct that the manual uses `M-<PAGEUP>' and not `M-<PRIOR>' (or
<M-prior>)? This also seems to be a source of confusion.


Summary:

1. Key-description producing and consuming functions should be able to use
both syntaxes: with and without angle brackets.

2. It would be good for the UI, the manual, and the output from the
key-description functions to all be on the same page wrt key notation.

3. IMO, `keyname' is almost always clearer than <keyname>, <KEYNAME>, and
`<KEYNAME>'.  I'd like to see us use that in both the UI and the manual.
Similarly, `M-keyname' is clearer than `M-<keyname>' and <M-keyname>.


[To be explicit: I'm not proposing any such changes before the release. But
some of the bugs (e.g. doc string of `read-kbd-macro') could perhaps be
fixed before then.]