RE: drew.adams@oracle.com: bug in read-kbd-macro

["Drew Adams" <drew.adams@oracle.com>]

    > The UI notation is not the same as the manual notation.
    
    What is ``the UI notation''?

What you see in messages and *Help*.  What `describe-key',
`key-description', and other, similar, Lisp functions produce.
The key-sequence notation used by Emacs everywhere, except in the
manual.

I explained this; see my previous messages in the thread.  I gave
multiple examples of both UI and manual notations, labeling them
as such.
    
    >     > 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.
    
    I think this is silly.  The printed version is more powerful
    than a plain text version, 

If it were, that would certainly not be because of those key
images.  The doc that corresponds more exactly to what the user
sees in the application is the "more powerful" doc, because it
gives the user more power, from better understanding.  The manual
should use the same notation as the UI, unless there is a good
reason not to.  Got a good reason?  "It's more powerful" is not a
reason; it's just a marketing claim, unless some extra power is
identified.

    and there's no need to go to the lowest common denominator
    just for consistency's sake.  It's good enough that the two
    are sufficiently similar.
    
    Btw, @var causes its argument to be typeset in italics in the
    printed version, but in the Info version it produces
    UPPERCASE.  Would you suggest to typeset it in upper-case in
    the printed manual as well, for consistency's sake?  It's
    absurd, I think.

This discussion is about key-sequence descriptions and key
descriptions.  We can start another thread to discuss typesetting
@var, if you like, but I might have nothing special to say about
that; I haven't really thought about it.

My point was not that there cannot be typographical differences
between print manual and online manuals.  I explicitly said that
there can be, and I explicitly stated that it's good, _"in
general"_ , for them to use the same notation (you quoted it,
above).  What I mean by that is other things being equal.  To
justify different notations, something should be gained, not
lost.

I don't have an opinion whether something is gained by using
italic in the printed manual.  Italic could of course be used in
the online manual also, so there needs also to be an argument for
something being gained by using non-italic uppercase in the
online manual.  Again, this is off topic.

[BTW, I do find the new use of italic in variables/parameters of
*Help* descriptions (e.g. `describe-function') somewhat _less_
readable than the previous use of non-italic uppercase, but that
would be yet a third discussion (off topic).  (To be clear, I'm
not arguing now for or against using italic for that.)  I'll no
doubt get used to that change.]

I'm much less concerned about notation differences between online
and print manuals than I am between the key-sequence notation
used in the UI (messages, *Help*) and in the manuals.  We should
teach the notation used in the UI, because that's what people see
when they use Emacs.  I don't see a need for, or anything gained
by, introducing a different notation for the manuals (especially
one that is different in each form of the manual).  While I can
imagine someone arguing that italic or uppercase is more readable
in print or on line, I have a hard time imagining someone arguing
that the difference between the various key-sequence notations is
for readability.

What's wrong with <S-tab> (UI)?  What's better about `S-<TAB>'
(manual)?  If the latter is better, then why don't we use it in
the UI too?  In fact, I said, in a different thread recently,
that I too slightly preferred S-<tab> to <S-tab>.  That was in
response to someone pointing out, correctly, that the modifier is
not part of the key - the angle brackets having been presented in
the manual as signifying keyboard keys (which they don't, in
cases like <mode-line>).

While I think that S-<tab> is marginally clearer and more correct
than <S-tab>, the real point is that the manual should use
whatever Emacs (that is, the UI) uses, because the manual is
there to describe Emacs.  If you prefer to look at that the other
way 'round, then that's OK too: the UI should use whatever the
manual uses.  If `S-<TAB>' is better, then it is the UI that
should change to use that.  My argument, however, was that
`S-tab' is the way to go, for both UI and manuals.

It's best not to have several different notations, _unless_ they
convey some advantages.  I don't see any advantage, and I do see
disadvantages (already mentioned).
    
    > 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
    
    The problem is not how to show sequence of keys, the problem
    is how to prevent the user from erroneously interpreting
    "Type `FOO'" as meaning that she should type those literal
    characters.  It's about possible reader's confusion, not
    about our notation.

I disagree that the discussion is not about key-sequence
notation.  That is _all_ I have been talking about, and I'm the
one who started the thread.

Presenting how to type something (how to effect a key sequence)
is entirely different.  That introduces a possible fourth
discussion (off topic).  Again, I don't have anything special to
say about that, not having really thought about it.

In any case, I don't see what the "problem" is in that regard.
There are lots of ways to unambiguously tell readers to effect a
key sequence (type keys, perform mouse actions).  However, a
key-sequence notation `p r i' is not the same as an instruction
to type `p', then `r', then `i'.  A key sequence `S-tab' is not
the same as an instruction to press and hold the `SHIFT' key
while hitting the `TAB' key.  A key sequence `mode-line
down-mouse-1' is not the same as an instruction to press
`mouse-1' over the mode line.

An instruction to input a key sequence is not the same as a
key-sequence description (notation), even if a key-sequence
description can often give users an idea how to effect that key
sequence.  Given an understanding of the notation, it can often
be enough to say "hit `C-b'" or "use `C-x f'".  That's one of the
reasons for having a key-sequence notation, of course: to help
compose instructions for effecting key sequences.

In this regard, the space-separation notation (again, already
used in the manual and the UI, for sequences such as `C-x 4 f')
is every bit as unambiguous and clear as the angle-bracket
notation.  Saying "use `mode-line down-mouse-1'" is just as clear
as saying "use <mode-line><down-mouse-1>".  Saying "type `f o o'"
is clear and unambiguous, given the convention that spaces
separate and `SPC' represents the space key in key-sequence
notation.  And, again, nothing prevents us from not using
key-sequence notation to provide instructions: "type `f', `o',
`o'".  Users will never erroneously interpret "type `foo', as you
fear, because we would never write that in the manual; we would,
and do, write "type `f o o'".

This is nothing new.  The only thing new would be to use _only_
the space-separation notation, and abandon the angle-bracket
notation as a case of multiplying things (notations)
unnecessarily - Occam's razor.  Extra, unnecessary stuff is
wasteful and a source of confusion.  What is so special about
<f10> that it needs to be in angle brackets, while `f' and `C-x 4
f' do not?

If users can understand `C-x 4 f' when they see it in the UI, and
they do, then I don't see any problem with using this
space-separation notation for all key sequences.  There really is
no need for two different key-sequence notations.