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

[Drew Adams]

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

The UI notation is not the same as the manual notation. That was
what this point (#1) is about: UI != manual.  You, I think, are
speaking of consistency within the manual.  My point was that the
manual writes `S-<TAB>' (including the quotes) but the UI writes
<S-tab>.  That is the inconsistency pointed out in #1.

This is not the end of the world, of course, but why not use the
same notation everywhere?  What would we lose by being consistent
in that way?  If both notations are unambiguous and clear, then
let's pick just one and stick to it everywhere.  Occam would like
us to.

[FWIW - I suspect the reason the manual notation is different
from the UI might be because someone opted for key images in the
printed manual (see #2), and those images already stood for the
angle-bracket notation of keys (e.g. <TAB>), so there was no way
to add modifiers, other than to put them "outside" the angle
brackets implicit in the printed image.  

That is, once you've replaced <TAB> with an image, adding `S-' to
that can only produce S-image, which translates to S-<TAB>, not
<S-tab>, for the online manual (and someone decided to add quotes
for extra beauty: `S-<TAB>').  Putting the modifier in the image
itself would presumably have violated the idea that the image
stood for a keyboard key - <S-tab> is not a keyboard key.

If I'm right about this, it means that the decision to use a
different notation in print (images) vs on line (angle brackets)
ended up also producing a notation difference between the manual
(both online and print) and the UI.  Dommage.]
    
    > 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.

No; it is possible.  Just do the opposite: bring the printed
version into line with the online version, even the non-graphic
(i.e. console) version, by using `next' for both.  Or, if you
don't like my suggestion to use quotes instead of angle brackets,
use <next> (or even <NEXT>, but without the image stuff) for
both.

The point is to use the same thing for both, and if one of them
is too fancy for the other medium, then that is obviously not the
one to try to use for both ;-).

    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.

Yes, no need to go there. This is not that complicated.

To be clear, point #2 is not very important, as long as the
printed manual explains its special typographical convention and
explicitly introduces the standard notation (that is, the
notation used for the UI).  IOW, it's OK to use a special
notation in the printed manual, but the real thing for users to
learn is the standard notation, the one they will encounter when
using Emacs.

I personally don't think we gain anything by using a special
typographical convention in the printed manual (especially one as
ugly as what we have now), but I want to be clear that if we do,
then we should at least point that out and present the standard
(that is, the UI) notation explicitly: <S-tab>, not `S-<TAB>'.
(Perhaps we do already; I didn't check.)
    
    > 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.

I explained (in the part that you omitted) that separation by
spaces (e.g. `p r i o r' vs `prior') is an alternative convention
for a key sequence, which disambiguates the two just as well, and
it is also used in the manual (and in the UI) today.

We write `C-x 4 f', not `C-x4f'.  We certainly don't write
<C-x><4><f>, and that is the proof that the angle-bracket
convention is not _needed_.  You can still argue that you want it
for some reason, but it is not needed.

So, we have two different conventions now for separating keys
within a sequence, and only one is needed.  Since we don't (thank
goodness!) write <C-x><4><f>, the single convention to adopt
would be space separation: `C-x 4 f' and `p r i o r' (vs
`prior').  Occam wants us to have only one convention; I want
that convention to be space separation.

The only case where confusion could arise with the
space-separation convention is when a space is used as part of
the key sequence, and that is easily dealt with by using the
description of the space key, `SPC': e.g. `p r i SPC o r'.  That
is not even a special case, but it's worth pointing out.
    
    > 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.

Ah, the ol' "I never heard anyone complain" argument...  Well, it
was a long time coming, but you finally got your first suggestion
to change this.  Hallelujah!  Rejoice!
    
    > 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.

Sorry you think so.  Do you perhaps also like the raised buttons
that pollute Customize?  Was I the first to complain about those
too?  Headache, in addition to nausea, for those.

Anyway, people often disagree about which appearance is more
appealing or easier on the eye.  (Some people write entire emails
in UPPERCASE.)  There are perhaps UI experiments that have tested
this kind of thing, but I don't know of any specifically.  Guess
we'll just have to recognize that we don't have the same
taste/preference in this regard ;-).

    This has been like that for ages.  

Right.  And you never heard anyone complain...

    Of course, if you wish to submit a change to texinfo.tex to
    make it look prettier, please do.

I'm not capable of that, I don't have the time, and I'm not sure
RMS would accept my contribution without papers from my employer.
I've made a suggestion about the notation.  If people like the
suggestion, then someone else can change texinfo.tex to realize
it.

Anyway, the point is moot I guess, as Richard has apparently
already decided - he agrees with you.
    
    > 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.

And in the UI?

Anyway, #6 was a response to the quote from the Texinfo manual
stating that the notation in the screenshot refers to "a name for
a key on a keyboard".  <TAB> is the name of a keyboard key, but
`S-<TAB>' is not - it describes a key sequence.  Key-sequence
notation is not just a chaining of keyboard key names - we don't
typically write <SHIFT><TAB> for this key sequence.

My gripe is not really with using angle brackets to describe
keyboard keys; it is with using them in key-sequence notation or
to refer to logical keys, such as <mode-line>.  If you want to
keep <PRIOR> as a name for the keyboard key only, that's OK by
me, though I don't think it's necessary.  I'd prefer to refer to
such keys always by their key-sequence notation, which is <prior>
in the UI, and which I propose should be just `prior'.  I don't
think we'll ever need to write about the <PRIOR> keyboard key, as
opposed to the <prior> logical key in a key sequence, so I really
don't care much about what keyboard-key notation we use.

There are, anyway, very few keyboard keys that we would ever
_need_ to refer to by name, to distinguish them from the
key-sequence notation for the same key.  Those are the modifier
keys.  All other keyboard keys - and plenty of non-keyboard keys
that also have multiple-letter names - can just use their
key-sequence notation for the key as well.  We can always use
<prior> (or, as I prefer, `prior') for both key and key sequence;
we can always use <mode-line> (or `mode-line').

It is different, however, for modifier keys.  It is only for
modifier keys that we might need to distinguish the key from its
use in a key sequence - and that is the point of point #7 (see
next).
    
    > 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.

Sounds reasonable to me, and I think that is already consistently
the case.

I agree, and that was, in fact, my point: this is true only for
modifier keys.  I singled out those keys here to point out that
they are different critters from keys such as `prior' (or
<PRIOR>), which can be (or can be part of) key sequences using
the same notation.

`prior' as a key is like `mode-line' (or <MODE-LINE> (manual) or
<mode-line> (UI)) as a key; it is not like <CTRL> as a key.  We
can have a key sequence `mode-line down-mouse-1' (or
`<mode-line><down-mouse-1>'), and we can have a key sequence
`C-down-mouse-1' (or `C-<down-mouse-1>' (manual) or
<C-down-mouse-1> (UI)), but we cannot have a key sequence
<CTRL><down-mouse-1>.  You might prefer to say that we could, but
it is not part of our notational convention.  We don't, in any
case.

You will also have noticed that the idea that the notation in the
screenshot refers to "a name for a key on a _keyboard_" cannot
even be applied to logical, non-keyboard keys such as
<mode-line> or <down-mouse-1>.

To the extent that we have a separate notation for keyboard keys,
as opposed to key sequences, I propose that we limit it to the
modifier keys.  At all other times, we can use the key-sequence
notation.

And the key-sequence notation to use is that of the UI:
<mode-line>, not <MODE-LINE>; <S-tab>, not `S-<TAB>'.

And the angle-bracket convention should be dropped - only the
space-separator convention should be used: `mode-line', not
<mode-line>, and `mode-line down-mouse-1', not
<mode-line><down-mouse-1>.