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

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

[Drew Adams]

> By "judgment call" I meant that a human should
> decide which case is which, and act accordingly.

Definitely.

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

[Drew Adams]

> > 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>).
> 
> I simply never saw a keyboard with a "next" key, so I don't know how
> it is labeled.  I left those as they were because of that.

<next> is how Emacs calls the "PageDown" key.  You did not leave that
as <next>.  Or maybe you meant that you left it as <PageDown> because
it is never labeled `next'?

> > These are inconsistencies within the manual, IMO.  They complicate
> > understanding unnecessarily.
> 
> They are not inconsistencies to me, because there's a reason for
> selecting each spelling, and I explained that reasoning.  Others are
> welcome to come up with different schemes, if they want, but I think
> in general too drastic changes should be avoided, because people are
> used to see "TAB" and "ESC".

TAB and ESC is also how Emacs (UI/help) refers to those, so no problem
there.

> > > 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.
> 
> If you mention the labels in just one place, it is as if you didn't
> mention them at all.  It's a large manual, and no one reads the
> section about why the keys are named like they are. 

Cross references.

> Most readers want
> to read what directly pertains to the subject they need now, and
> little else.  So the key sequences in the manual need to use a
> consistent naming scheme throughout, and not just in some obscure
> subsubsubsection.

The consistent naming scheme is the one Emacs itself uses.  It is
what users are used to seeing from Emacs.  It is what users will
see when they go back to the UI from the manual.

A "consistent" naming scheme that sometimes bases the name on a
key label and sometimes bases it on a Lisp symbol, and so on, is
unnecessarily complicated.  You can give a reasonable reason why
you named this or that key the way you did in the manual, but if
the reasoning has to go through multiple possibilities it is
unecessarily complicated.

Users should not need to know what the complicated rule is (or to
look it up, in the lone manual location where it is explained).
They should not wonder why sometimes this is done and sometimes
that, even if you have a good explanation for it.

> > > > > 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>
> 
> Sorry, that was incorrect: it should be <LEFT>, in all caps.  The
> others are correct.

On my keyboard, "Backspace" is as much a label as are "Delete" and
"Home".  And I have a pretty common, standard keyboard.  You will perhaps
argue that keyboards change over time and differ according to location.
Exactly.

The most that can and should be said wrt keyboard key labels is to give
some examples: `DEL' and <backspace> (which are not the same) are
sometimes labeled "Backspace".  <next> is sometimes labeled "Page Down".
<left> is sometimes labeled with a left-pointing arrow.  And so on.

If Emacs itself can refer to a key as <next> then so can the Emacs
manual.  Emacs does not jump up every time it writes <next> and say
that this key might be labeled "PageDown", "Page Down", or "PageDwn"
on your keyboard.  And neither should the manual.  It is enough to
have a short section of the manual that talks about this - key labels
vs Emacs key-sequence notation.

> > There are lots of occurrences of <Backspace>.
> 
> Before my changes, yes.  Now I see only one, in the Glossary.

OK.

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

[Eli Zaretskii]

> Date: Tue, 29 Apr 2014 12:38:00 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dmoncayo@gmail.com, 17362@debbugs.gnu.org
> 
> > > 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>).
> > 
> > I simply never saw a keyboard with a "next" key, so I don't know how
> > it is labeled.  I left those as they were because of that.
> 
> <next> is how Emacs calls the "PageDown" key.  You did not leave that
> as <next>.

Yes, I did leave it as <next>.

> > > > 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.
> > 
> > If you mention the labels in just one place, it is as if you didn't
> > mention them at all.  It's a large manual, and no one reads the
> > section about why the keys are named like they are. 
> 
> Cross references.

Doesn't help too much in this case.  You cannot ask people to go to
see that explanation each time they see a key sequence.

> > Most readers want
> > to read what directly pertains to the subject they need now, and
> > little else.  So the key sequences in the manual need to use a
> > consistent naming scheme throughout, and not just in some obscure
> > subsubsubsection.
> 
> The consistent naming scheme is the one Emacs itself uses.

Not good enough: Emacs sometimes calls several keys by the same name.
This is OK for key binding, but not for user manual descriptions.

> Users should not need to know what the complicated rule is (or to
> look it up, in the lone manual location where it is explained).
> They should not wonder why sometimes this is done and sometimes
> that, even if you have a good explanation for it.

Please read the manual, and tell me if this is needed.  I think
readers indeed will not wonder about any rules, because the text
speaks for itself, and so do the key names.  The rules are for those
who write the manual, and they are there to make the text speak for
itself.

> > > > There should be only these variants in the manual:
> > > >   <BACKSPACE>  <Delete>  <left> <Home>
> > 
> > Sorry, that was incorrect: it should be <LEFT>, in all caps.  The
> > others are correct.
> 
> On my keyboard, "Backspace" is as much a label as are "Delete" and
> "Home".  And I have a pretty common, standard keyboard.  You will perhaps
> argue that keyboards change over time and differ according to location.
> Exactly.

Not exactly.  I explained why I decided to use BACKSPACE.  Please go
back and re-read that.

As the keyboards change, so does the Emacs manual in this area, by the
way.  So there's no need (and no practical way) to adopt a naming
scheme that would endure changes in keyboards.

> The most that can and should be said wrt keyboard key labels is to give
> some examples: `DEL' and <backspace> (which are not the same) are
> sometimes labeled "Backspace".  <next> is sometimes labeled "Page Down".
> <left> is sometimes labeled with a left-pointing arrow.  And so on.

The manual already does that.

> If Emacs itself can refer to a key as <next> then so can the Emacs
> manual.  Emacs does not jump up every time it writes <next> and say
> that this key might be labeled "PageDown", "Page Down", or "PageDwn"
> on your keyboard.  And neither should the manual.  It is enough to
> have a short section of the manual that talks about this - key labels
> vs Emacs key-sequence notation.

The manual already does that, too.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Tue, 29 Apr 2014 12:09:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dmoncayo@gmail.com, 17362@debbugs.gnu.org
> 
> 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>).

I simply never saw a keyboard with a "next" key, so I don't know how
it is labeled.  I left those as they were because of that.

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

They are not inconsistencies to me, because there's a reason for
selecting each spelling, and I explained that reasoning.  Others are
welcome to come up with different schemes, if they want, but I think
in general too drastic changes should be avoided, because people are
used to see "TAB" and "ESC".

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

If you mention the labels in just one place, it is as if you didn't
mention them at all.  It's a large manual, and no one reads the
section about why the keys are named like they are.  Most readers want
to read what directly pertains to the subject they need now, and
little else.  So the key sequences in the manual need to use a
consistent naming scheme throughout, and not just in some obscure
subsubsubsection.

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

Sorry, that was incorrect: it should be <LEFT>, in all caps.  The
others are correct.

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

Before my changes, yes.  Now I see only one, in the Glossary.

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

[Eli Zaretskii]

> Date: Tue, 29 Apr 2014 22:20:20 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 17362@debbugs.gnu.org
> 
> > > There should be only these variants in the manual:
> > >   <BACKSPACE>  <Delete>  <left> <Home>
> 
> Sorry, that was incorrect: it should be <LEFT>, in all caps.  The
> others are correct.
> 
> > > 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>.
> 
> Before my changes, yes.  Now I see only one, in the Glossary.

And now there are none.

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

[Drew Adams]

> > > Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> > > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> > >
> > > IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> > > both act the same, however.)
> >
> > I'd also prefer "ESC" over "<ESC>" but then other strings like
> > "<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
> > accordingly.
> 
> Actually, the distinction should be between "ESC" (or "TAB" or "SPC")
> the key vs "ESC ESC ESC" the key sequence typed from the keyboard.  So
> not every <FOO> should suddenly become "FOO", it's a judgment call.

A difference in syntax for keyboard keys vs key sequences should not be
subject to judgment calls.  There are presumably clear-cut rules defining
the two different syntaxes.

I suppose that a particular sentence might be ambiguous as to which is
meant, but in that case perhaps the sentence needs rewording to make clear
which is meant.  In such a case, the meaning that users take from the text
(keyboard key vs key sequence) should not depend only on the syntax used.
Preferably the rest of the sentence would make clear which meaning is intended.

Anyway, feel free to make any judgments you feel appropriate wrt this
particular bug and the various occurrences in the manual (and the other
Emacs manuals).  And if you judge that there is no inconsistency
anywhere then feel free to close it.

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

[Eli Zaretskii]

> Date: Mon, 28 Apr 2014 08:39:06 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: drew.adams@oracle.com, 17362@debbugs.gnu.org
> 
> > Actually, the distinction should be between "ESC" (or "TAB" or "SPC")
> > the key vs "ESC ESC ESC" the key sequence typed from the keyboard.  So
> > not every <FOO> should suddenly become "FOO", it's a judgment call.
> 
> A difference in syntax for keyboard keys vs key sequences should not be
> subject to judgment calls.  There are presumably clear-cut rules defining
> the two different syntaxes.

The rules might be clear to humans, but not to a global
search-and-replace.  By "judgment call" I meant that a human should
decide which case is which, and act accordingly.

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

[Drew Adams]

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

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?

I thought that we used uppercase only for the ASCII control chars: TAB,
RET, ESC, and DEL, and not for key sequences involving pseudo function
keys <tab> and <backspace>.  (I also thought that we specifically did
NOT enclose the former in angle brackets, but I guess that's another
story.)

You will perhaps say that <TAB> refers only to the keyboard key, and
not to an Emacs key sequence.  In that case, it should not appear as
part of a key sequence notation, IMO.

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

It seems to me that:

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

Let me know if I am misunderstanding something.  I admit to feeling
a bit confused now by the various notations.  I thought it was pretty
straightforward: just ASCII control char names (uppercase), function
keys and pseudo function keys (lowercase, in angle brackets).  It no
longer seems so straightforward and simple.

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

[Eli Zaretskii]

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

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

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

[Eli Zaretskii]

> Date: Tue, 29 Apr 2014 10:27:03 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dmoncayo@gmail.com, 17362-done@debbugs.gnu.org
> 
> > > 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.

I'm not talking about help, I'm only talking about the manual.  The
bug report was about inconsistencies in the manual.  At least that's
how I perceived it, and that's the only issue I set out to fix.

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

Which part is unclear?

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

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

If that's the issue, then (a) it was nowhere clear from your original
bug report, and (b) I will have nothing to do with it, sorry.  I don't
care enough about it to work on that.

I only fixed inconsistencies in the manual, without any relation to
what Emacs says in help mode.

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

Perhaps it could be nice (although it never bothered me), but I think
it's close to impossible now, due to various historical reasons.  In
any case, I'm not going to do anything about this, someone else will
have to step forward.  I found your complaint about inconsistencies in
the manual justified, and I fixed that; my job here is now done.

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

[Josh]

On Tue, Apr 29, 2014 at 10:51 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> > Date: Tue, 29 Apr 2014 10:27:03 -0700 (PDT)
> > From: Drew Adams <drew.adams@oracle.com>
> > Cc: dmoncayo@gmail.com, 17362-done@debbugs.gnu.org
> >
> > > > 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.
>
> I'm not talking about help, I'm only talking about the manual.  The
> bug report was about inconsistencies in the manual.  At least that's
> how I perceived it, and that's the only issue I set out to fix.

Sorry to be mentioning this after you committed your changes, but I
wanted to comment about the impact of these changes on new users.
Difficulty specifying key bindings correctly is fairly common among
newer users, and I think that this difficulty is worsened by
occurrences in the documentation of non-canonical (with respect to
kbd arguments) key notation.  There's an EmacsWiki page[0] about key
binding notation that reads in part, "Use C-h k to find out how Emacs
describes the key sequence, and copy & paste that into your kbd
string."  It would be good if the info manual used the same notation.

http://www.emacswiki.org/cgi-bin/wiki?KeyBindingNotation

Josh

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

[Drew Adams]

> Sorry to be mentioning this after you committed your changes, but I
> wanted to comment about the impact of these changes on new users.
> Difficulty specifying key bindings correctly is fairly common among
> newer users, and I think that this difficulty is worsened by
> occurrences in the documentation of non-canonical (with respect to
> kbd arguments) key notation.  There's an EmacsWiki page[0] about key
> binding notation that reads in part, "Use C-h k to find out how Emacs
> describes the key sequence, and copy & paste that into your kbd
> string."  It would be good if the info manual used the same notation.
> 
> http://www.emacswiki.org/cgi-bin/wiki?KeyBindingNotation

That's what the discussion here after Eli's fix has been about.

But this is not really the best place to discuss or propose it.
Why don't you file another bug for this?

I have brought it up before, in emacs-devel and perhaps in one or
more bug reports, but maybe there is another chance for such a
simplification.

Unfortunately, Eli opposes it so far, and he is no doubt the
person the most interested in working on the manual (and the most
familiar with it and with its build tools).  But AFAIK that does
not necessarily mean that the question is closed forever.

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

[Eli Zaretskii]

> From: Josh <josh@foxtail.org>
> Date: Tue, 29 Apr 2014 14:55:30 -0700
> Cc: Drew Adams <drew.adams@oracle.com>, 17362@debbugs.gnu.org
> 
> Sorry to be mentioning this after you committed your changes, but I
> wanted to comment about the impact of these changes on new users.
> Difficulty specifying key bindings correctly is fairly common among
> newer users, and I think that this difficulty is worsened by
> occurrences in the documentation of non-canonical (with respect to
> kbd arguments) key notation.  There's an EmacsWiki page[0] about key
> binding notation that reads in part, "Use C-h k to find out how Emacs
> describes the key sequence, and copy & paste that into your kbd
> string."  It would be good if the info manual used the same notation.

I agreed that it would probably be good, but I don't see how this goal
could be achieved in practice, given that the user manual's main goal
is not to explain how to change key bindings, but rather how to use
the existing ones.

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

[Drew Adams]

> I'm not talking about help, I'm only talking about the manual.  The
> bug report was about inconsistencies in the manual.  At least that's
> how I perceived it, and that's the only issue I set out to fix.

Yes, thank you for that.

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

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

(And yes, this discussion is outside this bug report.  I did not
ask in the report that you fix all key-sequence inconsistencies in
the manual.  But that's what the current discussion is about.
That and the inconsistencies between the notations in the manual
and the notation in the Emacs UI.

> > 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.
> 
> If that's the issue, then (a) it was nowhere clear from your original
> bug report, and (b) I will have nothing to do with it, sorry.  I don't
> care enough about it to work on that.

1. Yes, it is outside this bug report.
2. Too bad you are not interested in it, but so be it.

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

But yes, beyond inconsistencies within the manual, the larger issue is
to get the manual in sync with the rest of Emacs, so there it uses the
same, single, key-sequence notation.  And yes, that is outside this
bug report.

I am OK with (what I guess is) what you have fixed for this bug report.

> > 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>?
> 
> Perhaps it could be nice (although it never bothered me), but I think
> it's close to impossible now, due to various historical reasons.  In
> any case, I'm not going to do anything about this, someone else will
> have to step forward.  I found your complaint about inconsistencies in
> the manual justified, and I fixed that; my job here is now done.

Thank you for that.

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

[Eli Zaretskii]

> Date: Tue, 29 Apr 2014 11:12:22 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: dmoncayo@gmail.com, 17362@debbugs.gnu.org
> 
> > I'm not talking about help, I'm only talking about the manual.  The
> > bug report was about inconsistencies in the manual.  At least that's
> > how I perceived it, and that's the only issue I set out to fix.
> 
> Yes, thank you for that.

You are welcome.

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

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

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

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

[Drew Adams]

Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.

IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
both act the same, however.)



In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-04-21 on ODIEONE
Bzr revision: 117005 dancol@dancol.org-20140421180019-po4wdeg7gqvvlh5d
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

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

[Dani Moncayo]

> Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
>
> IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> both act the same, however.)

I'd also prefer "ESC" over "<ESC>" but then other strings like
"<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
accordingly.

-- 
Dani Moncayo

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

[Drew Adams]

> > Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> >
> > IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> > both act the same, however.)
> 
> I'd also prefer "ESC" over "<ESC>" but then other strings like
> "<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
> accordingly.

Yes, FWIW, IMO they should be.  But this bug will be fixed if things are
made consistent either way.

Oh, and BTW there are also inconsistencies for those others, including in
nodes: `CUA Bindings', `Misc File Ops', `File Conveniences', `Filesets',
`Speedbar', `Bidirectional Editing', `Other C Commands', `Image Dired',
`Printing Package', `MS-DOS Printing', `Help Mode', `Rectangles', `Special
Isearch', `Regexp Search', `Keyboard Macro Step-Edit', `Marks vs Flags',
`Counting Days', `General Calendar', `HTML Mode', `Windows Keyboard'.

[A related bug?: `<DELETE>' in nodes `Hungry Delete', `MS-DOS Keyboard',
and `Glossary'.  Is `<delete>' what is meant here?  Likewise, you can
find occurrences of `<BACKSPACE>' instead of `<backspace>'.]

And of course there is the way that Emacs itself writes such keys in its
help.  See, e.g., node `International Chars'.  Sometimes Emacs writes
`<RET>' when it communicates with users; sometimes it writes `RET'.

[IMO - but this has been rejected by Emacs Dev more than once - there is 
NEVER any reason to use the angle-bracket notation - it was misguided to
introduce it at all.  And in my own libraries I make it optional whether
Emacs uses angle brackets or not (as far as Lisp is concerned).  For
example, library `naked.el' provides an alternative to `kbd' that lets
you choose the format.  http://www.emacswiki.org/emacs-en/NaKeD,
http://www.emacswiki.org/emacs-en/naked.el]

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

[Eli Zaretskii]

> Date: Mon, 28 Apr 2014 08:25:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17362@debbugs.gnu.org
> 
> > > Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> > > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> > >
> > > IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> > > both act the same, however.)
> > 
> > I'd also prefer "ESC" over "<ESC>" but then other strings like
> > "<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
> > accordingly.
> 
> Yes, FWIW, IMO they should be.  But this bug will be fixed if things are
> made consistent either way.

I made it consistent in the way described below.

> Oh, and BTW there are also inconsistencies for those others, including in
> nodes: `CUA Bindings', `Misc File Ops', `File Conveniences', `Filesets',
> `Speedbar', `Bidirectional Editing', `Other C Commands', `Image Dired',
> `Printing Package', `MS-DOS Printing', `Help Mode', `Rectangles', `Special
> Isearch', `Regexp Search', `Keyboard Macro Step-Edit', `Marks vs Flags',
> `Counting Days', `General Calendar', `HTML Mode', `Windows Keyboard'.

Did this as well.

> [A related bug?: `<DELETE>' in nodes `Hungry Delete', `MS-DOS Keyboard',
> and `Glossary'.  Is `<delete>' what is meant here?  Likewise, you can
> find occurrences of `<BACKSPACE>' instead of `<backspace>'.]

And this.

Most of the places where I found a need to change the manual, I
decided that using @key (which produces "<FOO>" in Info) was TRT.  I
know that Drew and Dani don't like this, but this is how Texinfo
manuals in general and the Emacs manual in particular are written
since day one.

My changes are committed as emacs-24 branch revisions 117028 and
117032.

For the record, here are the guidelines I used to fix this stuff
consistently (if there's a good place to document that, please point
it out):

  . Use @key whenever keyboard input references a key whose label or
    name is longer than 1 characters, like "TAB" or "Delete".  This is
    to avoid confusion between pressing a single key and literally
    typing "T A B" (3 keys) or "D e l e t e" (6 keys).

  . In all other cases, keyboard input typed by the user should be in
    @kbd.  When a key sequence includes both kinds of input, use @kbd
    on the outside and @key inside, as in @kbd{M-x foo @key{RET}}.
    (It is harmless to say @kbd{@key{RET}}, but in that case @kbd is
    redundant, as it doesn't have any useful effect.

  . Key names inside @key should be capitalized as follows:

    - If a key has a label, its name should follow the usual
      capitalization of the label, as in @key{Alt} or @key{PageUp}.

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

   . When the text talks about control characters, such as ^L or ^J,
     do _not_ use @key (as in @key{Ctrl-L}), to avoid confusing them
     with keystrokes.  Instead, use @samp.

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

[Eli Zaretskii]

> Date: Mon, 28 Apr 2014 16:49:38 +0200
> From: Dani Moncayo <dmoncayo@gmail.com>
> Cc: 17362@debbugs.gnu.org
> 
> > Emacs manual: contrast node `Menu Bar' with node `Quitting'.  The former
> > writes `ESC ESC ESC'; the latter writes `<ESC> <ESC> <ESC>'.
> >
> > IMO, the former is preferable.  (Note that (kbd "ESC") and (kbd "<ESC>")
> > both act the same, however.)
> 
> I'd also prefer "ESC" over "<ESC>" but then other strings like
> "<TAB>", "<SPC>", "<RET>" or "<DEL>" should also be changed
> accordingly.

Actually, the distinction should be between "ESC" (or "TAB" or "SPC")
the key vs "ESC ESC ESC" the key sequence typed from the keyboard.  So
not every <FOO> should suddenly become "FOO", it's a judgment call.