bug#20135: 25.0.50; Emacs manual typos for key bindings

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

First, thanks for making the fixes you made.  That helps.

> > Do we write `<S-up>' or `S-<up>'?  Or do we use both conventions, and if
> > so, are they interchangeable (same meaning)?
> 
> S-<up> is the right way for the manuals.

Any chance to revisit that?  Why use different notations for help and
manual?  Anyway, that is not the particular issue of this bug report.

> > Another question is about whether, aside from special cases (which are
> > already called out, AFAIK), function-key names should be written using
> > uppercase.  For example, is `<S-RIGHT>" correct, or should it be
> > `<S-right>" (or `S-<right>')?
> 
> We've been though this before, and AFAIK the manual was fixed to be
> consistent at that time.

I know nothing about whether that was the case.  But it does not seem to
be consistent now, at least.

> > In the manual, it seems that the more common syntax is `S-<...>', not
> > `<S-...>'.  However, in doc strings the opposite seems to be true (?).
> 
> In the doc strings, that's substitution, right?  It's not that these
> are written verbatim in the doc string, right?  If so, they are
> formatted how the relevant APIs (key-description, I believe) do it.

Correct.  It is generally `key-description' that provides help commands
with their syntax.

Which means that this is the syntax users will be likely to see most
often.  Which means that it might well be the syntax that they will
try (mistakenly) to use when searching the manual, for instance.

> > 1. Node `View Mode': <S-<SPC>>.  Presumably should be S-<SPC>.
> 
> Fixed.
> 
> > 2. Node `Org Mode': <S-TAB>.  Should be S-<TAB>, I'm guessing - or
> >    possibly S-<tab>, depending on which key is meant.
> 
> Fixed.
> 
> > 3. Node `Setting Mark': S-<RIGHT>.  Should be S-<right>, I think.
> >
> > 4. Node `Indentation Commands': S-<LEFT>, S-<RIGHT>.  Should be
> >    S-<left>, S-<right>.  (Also: <LEFT> and <RIGHT> should be <left> and
> >    <right>.)
> >
> > 5. Node `Setting Mark': S-<RIGHT>.  Should be S-<right>.
> >
> > 6. Node `User Input': M-<LEFT> should be M-<left>.
> >
> > 7. Node `Moving Point': C-<RIGHT>, M-<RIGHT>, C-<LEFT>, M-<LEFT> should
> >    be C-<left>, M-<left>, C-<right>, M-<right>.
> 
> No, uppercase is OK here, for consistency with TAB, SPC, etc.  Again,
> we've been through this before.

I don't recall being through all of this before.  But if you insist on
this (I disagree, obviously), then you will likely want to "fix" the
opposite occurrences - e.g. `<up>' etc. that you will find throughout
the manual.

But why would you give as a reason being consistent with TAB, SPC, DEL,
etc., which are *exceptions* (correponding to ASCII names)?

Why not speak about consistency with the other function keys and
pseudofunction keys - <prior>, <next>, <home>, etc.?

Presumably, one of us is missing something wrt "consistency".

Even in the same node, e.g. `Insert in Picture', you will find
3 different ways of writing such keys:

 `C-c <RIGHT>' (uppercase)
 `C-c <Home>'  (title case)
 `C-c <prior>' (lowercase)

Surely there is something to be fixed there, no?  How does Emacs 
itself refer to those keys?  Ask it: `C-h k' gives this:

 `C-c <right>'
 `C-c <home>'
 `C-c <prior>'

> > 8. Node `Minibuffer History': <M-n> should presumably be M-n.
> 
> No, it should be `M-n' (with the quotes).  

Agreed, and that's what I meant.  I left off the quotes because of
the variability I mentioned wrt whether they are used in the manual.

> Fixed.
> 
> >    (Also, <UP> and <DOWN> should be <up> and <down>.
> 
> No, that's OK.

See above.  In that case, please "fix" all of the occurrences of
<up> and <down>.  And all of the other (pseudo)function keys - <next>,
<prior>, etc.  There are *lots* of them.

I disagree that uppercase should be used, but if you're really making
such a call then please apply it consistently.

> > 9. Node `Basic Indent': <C-j> should be just C-j.
> 
> Should be `C-j'; fixed.
> 
> > 10. Node `Custom C Indent': <C-M-q> should be just C-M-q.
> 
> Again, `C-M-q'; fixed.
> 
> > 11. Node `Term Mode: <C-c> should be just C-c.
> 
> `C-c'; fixed.
> 
> > 12. There is also inconsistency in whether such keys are enclosed in
> >    quotes.  Node `Rmail Scrolling' has both notations mixed even in the
> >    same sentence (e.g., <SPC>, but `S-<SPC>'):
> 
> That's OK: a single key can omit the quotes; a sequence should not.
> 
> > 13. I wonder too about the function keys being written with uppercase:
> >    <F9> instead of <f9>.  In *Help* buffers (e.g. from `C-h k') they are
> >    written using lowercase.
> 
> Again, the manuals are consistent: all named keys are uppercased.

Dunno whether we are talking about "named keys" or about key sequences,
or both.  But in any case, that's not what I see - at all.

And I disagree that they should be.  (Just one opinion, but most of the
manual seemes to agree with me, as does help.)

> If we want the doc strings to follow suit, the relevant primitives should
> be changed to follow suit.

I don't want to change the doc strings to follow suit.  I think the manual
should reflect Emacs itself: its doc strings, help output, `key-description'.

When you interact with Emacs in any way (except for reading the manual),
this is how it talks about its key sequences.

> > For example, if you think that <UP> is correct, then search also for
> > <up>.  You will find, I think, that what I proposed is used more
> > consistently.
> 
> I did that in the past, and I don't think we have any inconsistencies
> left.  Feel free to point out any you find.

See what I already wrote.  Start with `Moving Point', for instance.
And `Org Mode'.  And `Minibuffer Edit'.  And `Yes or No Prompts'.
And `Scrolling'.  And `Scroll Calendar'.  And `Docview Navigation'.
And `Insert in Picture'...

You can search as well as I.  Try `C-s <next>`...  Then move on to another
pseudofunction key.  And another...

I think that you will find that, except perhaps for those that you "fixed"
the last time around (I don't recall that time, but you apparently do), the
vast majority are written using lowercase (as they are in help buffers).

> > But there does seem to be a general disconnect between what is shown in
> > *Help* by the help commands and what is shown in the manual by Info.
> > Help uses <S-foo> whereas the manual uses S-<foo>.
> >
> > To me, we should use the same notation for both, and I would vote for
> > the manual to fit what help uses.  That is, I would suggest that we
> > (consistently) use what `key-description' returns.
> 
> I won't object.

That's good news.