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

[Eli Zaretskii]

> From: "Drew Adams" <address@hidden>
> Date: Tue, 26 Sep 2006 08:02:07 -0700
> 
> 1. It's useful to have the UI notation (everywhere) and the manual notation 
> be the same, in general. It is a hindrance to have them different.

The manual notation for a certain key should be the same, anything
else is a bug that should be reported and fixed.  For example, the
`next' key should be spelled as @key{NEXT} everywhere in the manual's
text, and produce "<NEXT>" in the Info format.

> 2. It's useful to have the same notation for both online and printed manual, 
> in general.

Given how @key is typeset in the printed version, this is clearly
impossible, except in the graphics session of Emacs, and then only if
we hide the text of the Info file and show some image in its stead.
Given our quite negative experience with hiding parts of the Info
text, I'd say it's unwise to go that way in this case.

> 3. It's useful to use the same notation convention for all key sequences. It 
> misleads to write `a' and `]' one way and `prior' another way (<PRIOR>).

There's a method to this, which should probably be explained better in
the Texinfo manual than it is now: <PRIOR> (produced by @key) is used
to distinguish it from the sequence of letters P, R, I, O, R.  That
is, @key is for those cases where you mean a single key labeled with a
name, and where, were you to say `PRIOR', the reader could have
confused that to think she should type the above sequence of
characters one after the other, instead of pressing a single key.

> 4. `prior' is much more readable than the kind of notation shown in
> your screenshot.

I disagree.  FWIW, I never heard anyone complaining about how Texinfo
typesets @key.  YMMV, of course.

> Frankly, that looks like someone's first half-day playing with PowerPoint or 
> Word, a hangover from font binging. After a few pages dense with key and 
> key-sequence descriptions, that begins to nauseate. 

A wild exaggeration, IMHO.  This has been like that for ages.  Of
course, if you wish to submit a change to texinfo.tex to make it look
prettier, please do.

> 6. <S-tab>, `S-<tab>', S-<tab>, `S-TAB', and S-TAB are _not_ names of keys on 
> a keyboard. They are descriptions of key _sequences_.

I think they should be written as @address@hidden and appear as
`S-<TAB>', and the other variants are in error.

> 7. CTRL, META, ALT, and so on, might be names of keys on many keyboards, but 
> they are not names of key sequences.

They are the names of keys.  When the manual talks about them as
separate keys, it should use @key, yielding <CTRL>, <META>, etc.  When
it describes them as modifiers of other keys, they should be in @code
or @samp and appear as C-, M-, etc.  I believe anything else is again
an error in the manual that should fixed.