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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 29 Apr 2014 08:40:52 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dmoncayo@gmail.com, 17362-done@debbugs.gnu.org
> 
> >     - If a key does not have a label, its name should be in all caps,
> >       as in @key{TAB} or @key{META}.
> > 
> >     - There are 2 exceptions to the last 2 rules, both for historical
> >       reasons:
> > 
> >       * @key{BACKSPACE}, although many keyboards have a "Backspace"
> >         label on it.
> > 
> >       * @key{ESC}, which is labeled "Esc".
> 
> Eli, are you saying that you have replaced <delete>, <backspace>, etc.
> everywhere with <DELETE>, <BACKSPACE>, etc., or that you think it is
> appropriate to do so?

Only for BACKSPACE (and, of course, only in the manual).  It's still
"Delete" (because that's the label on the key).  ESC and TAB and SPC
and RET were always in caps, so they stay in caps.

> Seems like that would be a big change from the past and a change 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.

> You will perhaps say that <TAB> refers only to the keyboard key, and
> not to an Emacs key sequence.

I'm not sure I understand what you mean by "an Emacs key sequence".
How does it differ from TAB the key?

Again, I only changed how keys are referenced in the manual in the
context of documenting keybindings.

> And I would have thought that the keyboard keys would anyway be
> written the same as they are on the keyboard: Tab, Backspace, Delete,
> Esc, not <TAB>, <BACKSPACE>, <DELETE>, <ESC>.

On may keyboards, TAB and BACKSPACE have no labels, and the
traditional DEL key didn't have one, either.  I agree that nowadays
the situation is not 100% clear, but I simply chose to go with
tradition in these cases.

> 1. The way Emacs talks to users, via `kbd', `edmacro-parse-keys', and
>    help output in general should not be changed.
> 
> 2. The doc (manual) should follow the same conventions as `kbd',
>    `edmacro-parse-keys' and help output in general.
> 
> I am more concerned about #1 than #2.  I don't actually see you
> proposing any change wrt #1 so far, which is good.

I didn't propose and didn't change anything under #1.  As for #2, I
think it's impossible to satisfy that without changing significantly
how we describe keys in the manual.

> I do not, however, see a good reason why Emacs doc (manuals) should
> represent key sequences differently than Emacs help does.  That kind
> of goes against Occam's razor, multiplying things unnecessarily.

No reason but history and Texinfo style guidelines.