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

[Drew Adams]

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

<Delete> is not how Emacs refers to the key in help.  And neither is
<BACKSPACE>.  Emacs help calls these <delete> and <backspace>, AFAICT.

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

What does that mean?

Why write these key sequences differently in the manual from how Emacs
writes them in help?  Emacs writes <backspace>.  Why write <BACKSPACE>?
Emacs writes <delete>.  Why write Delete or <Delete>?

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

You are the one who has always reminded me that the manual writes
keyboard keys differently from how it writes key sequences.  I'm
concerned only with the latter.  If for you there is now no
difference, great - then it's only about how the manual writes key
sequences.

My point is that the manual should write key sequences the same way
Emacs writes them interactively, e.g., in help output.  It does not
refer to a <BACKSPACE> key or a Backspace key or a <CNTL>, <Control>,
Control, or Ctrl key.  Emacs help writes <backspace> and C- in key
sequences.

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

That's what we're talking about.  (But key sequences as documented,
not just "keybindings", which can be defined using a multitude of
Elisp formats/sexps.)

> > 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 ma[n]y 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.

I think Emacs has changed its "tradition" over time.  In Emacs 20
there are no angle brackets in the UI, for instance (there are some
in the manual).  Emacs 20 help writes `next', not `<next>' (as now).

And neither Emacs 20 nor Emacs 24 help output writes `<NEXT>' (as
appeared in the Emacs 20 manual) or `<BACKSPACE>' (as appears in
the manual now).

`describe-key' outputs `C-x <home>', but the manual writes
`C-x <Home>'.  Go figure.  Help writes `<left>', `<C-left>',
`<home>', and `<C-home>'.  But the manual writes `<left>',
`C-<left>', and `<Home>' (capitalized).

This is gratuitous confusion.  Emacs has a well-defined way of
representing key sequences - `kbd' is based on it.  Why not use
this single, well-defined syntax in the manual as well as the
interactive help?

It is pretty clear that for Emacs help output `TAB' is not the same
thing as `<tab>'.  The latter is a (pseudo) function key; the former
is `C-i'.  Why should the manual write <TAB>?

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

Dunno what that means.  But having the manual in sync with interactive
Emacs (e.g. help) would simplify things, not complicate them.  For both
Emacs maintainers and Emacs users, once the change is made.

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

Sounds like a cop-out, to me - but please tell me I'm wrong.  Do you
even agree that key sequences should be written the same way in the
manual as in the rest of Emacs?  Do agree that the manual, like the
rest of Emacs, should write <C-left> and not C-<left>, <C-home> and
not C-<Home>?