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

[Eli Zaretskii]

> Date: Wed, 18 Mar 2015 11:34:14 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20135@debbugs.gnu.org
> 
> > > 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?

Not for the manuals: this is how makeinfo translates @kbd{S-@key{up}},
which is how one should write modified keys in Texinfo.

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

As I said, feel free to point out specific inconsistencies, keeping in
mind that upper-case is the rule.

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

Let's not reiterate old arguments.

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

Where a key has a name printed on it, we should try using that name
literally, except when there's some tradition to the contrary.

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

Then you should be posting this bug report to the Texinfo list,
because they will have to change the Info output.

> You can search as well as I.

Sorry, not enough time.