bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'

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

> > > > > > from how Emacs itself communicates with users.  AFAIK, Emacs
> > > > > > writes <delete> for the Delete key etc.  The rule for function
> > > > > > keys and pseudo function keys has always been to use lowercase
> > > > > > (in angle brackets), no?
> > > > >
> > > > > Yes, because they are symbols.  I did nothing about symbols, of
> > > > > course.
> > > >
> > > > What does that mean?
> > > Which part is unclear?
> >
> > Apparently you agree that the rule for function keys is lowercase.
> > Yet you leave some of them capitalized or uppercase?  And the reason
> > is because those that you make lowercase are symbols?
> 
> They are symbols used in Lisp code, whereas the other kind are words
> used in the user documentation.

I understand.  Emacs itself speaks with one voice here, however, which
is less confusing for users, IMO.

Users, especially non-Lispers, should not be concerned with whether a
given key name corresponds to a Lisp symbol.  They should not need to
know or guess that you call a key <Delete> because you feel that
"Delete" is sufficiently common as the name printed on the keyboard
key, even though Emacs refers to that key as <delete>.

And you write <left>, using the Lisp symbol name `left', because what
is printed on the keyboard key is an arrow, not "Left".  And yet for
<next>, the manual refers to it as both <next> and <PageDown> (in
Emacs 20 it was referred to as (only) <NEXT>).

These are inconsistencies within the manual, IMO.  They complicate
understanding unnecessarily.

It would be much clearer to refer to these keys, in key sequences,
always as <delete>, <left>, and <next>.  Nothing prevents the manual
from also saying that such keys might be labeled "Delete", "<--"
(using an actual arrow symbol in the manual), and "PageDown".  But
such names should not appear in key sequences - in the manual or
anywhere else.

> > > > Emacs writes <backspace>.  Why write <BACKSPACE>?  Emacs writes
> > > > <delete>.  Why write Delete or <Delete>?
> > >
> > > See the guidelines I used to decide on names and capitalization, I
> > > tried to explain why I choose this or that convention.
> >
> > The convention used should be the one that Emacs itself uses to
> > write key sequences.
> 
> I disagree.  The manual should make it easier for the reader to
> identify the keys it talks about.  For that reason, using the keys'
> labels is IMO more useful and efficient than using their lowercase
> variants.

See above.  The manual can mention commonly used key labels, to help
users make connections.  But it makes little sense for the manual
to represent these keys differently in key sequences from the way
Emacs itself represents them.

> > > I only fixed inconsistencies in the manual, without any relation to
> > > what Emacs says in help mode.
> >
> > You fixed only some inconsistencies in the manual, but that is OK
> > for this bug report.  It is inconsistent to use <BACKSPACE> sometimes
> > and <Backspace> other times, <DELETE> and <Delete>, <left> and <Home>,
> > and so on.
> 
> There should be only these variants in the manual:
>   <BACKSPACE>  <Delete>  <left> <Home>
> 
> If you find others, please report them as documentation bugs.  I tried
> to fix them all, but maybe I missed some; it is a large manual.

There are lots of occurrences of <Backspace>.  And yes, it is a large
manual.  Keeping multiple representations only makes it more difficult
for people to correct and maintain the manual, I'm guessing.

Feel free to close this bug, and thanks for doing what fixing you
have done.  Every little bit helps.