bug#3516: 23.0.94; function key names in Info

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

emacs -Q
C-h r
g keys
 
We see things like <F1>, <F2>, <RET>, and <ESC> without single
quotes. Similarly, in other parts of the manual.
 
Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?
 
We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. Likewise,
we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), but not `<ESC>'.
 
The notation used does not seem consistent.
Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"?
 
(This also has the side effect of not fontifying, in contexts where
`...' is fontified.)
 
In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 9 Jun 2009 09:11:07 -0700
> Cc: 
> Reply-To: Drew Adams <drew.adams@oracle.com>, 3516@emacsbugs.donarmstrong.com
> 
> emacs -Q
> C-h r
> g keys
>  
> We see things like <F1>, <F2>, <RET>, and <ESC> without single
> quotes. Similarly, in other parts of the manual.
>  
> Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?
>  
> We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. Likewise,
> we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), but not `<ESC>'.
>  
> The notation used does not seem consistent.
> Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"?

Please show here the Texinfo sources, not just the text from the Info
manual.  I'm not saying that all you report is necessarily correct,
but it could be: ESC and RET are both characters and keys.  In the
character context, ESC and RET are correct, while in the key context,
`<ESC>' and `<SPC>' are correct (the latter comes from @key, and I
don't remember now whether @key produces the quotes in addition to
<..>).

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

> > emacs -Q
> > C-h r
> > g keys
> >  
> > We see things like <F1>, <F2>, <RET>, and <ESC> without single
> > quotes. Similarly, in other parts of the manual.
> >  
> > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?
> >  
> > We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. 
> > Likewise, we use `<ESC>C-h' (which should be `<ESC> C-h', BTW),
> > but not `<ESC>'.
> >  
> > The notation used does not seem consistent.
> > Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"?
> 
> Please show here the Texinfo sources, not just the text from the Info
> manual.  I'm not saying that all you report is necessarily correct,
> but it could be: ESC and RET are both characters and keys.  In the
> character context, ESC and RET are correct, while in the key context,
> `<ESC>' and `<SPC>' are correct (the latter comes from @key, and I
> don't remember now whether @key produces the quotes in addition to
> <..>).

I don't have the Texinfo sources.

I'm just an Emacs user reporting what seems to be an Emacs bug - in Info. You
are the Texinfo & Info expert, and you will know better than I what is the
appropriate Texinfo coding. You decide, after looking over my bug report and the
Texinfo sources or whatever.

For my part, I was referring to (or trying to refer to) passages that talk about
keys, not characters. To me, key sequences should be wrapped in `...', even when
they have <...>. To me, the key sequence should be written `<SPC>' even if the
character is written SPC. It sounds like that is what you're saying also. It is
not, however, what I see in the manual in various places, such as the node I
mentioned.

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 10 Jun 2009 15:33:50 -0700
> 
> > > We see things like <F1>, <F2>, <RET>, and <ESC> without single
> > > quotes. Similarly, in other parts of the manual.
> > >  
> > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?
> > >  
> > > We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. 
> > > Likewise, we use `<ESC>C-h' (which should be `<ESC> C-h', BTW),
> > > but not `<ESC>'.
> > >  
> > > The notation used does not seem consistent.
> > > Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"?
> > 
> > Please show here the Texinfo sources, not just the text from the Info
> > manual.  I'm not saying that all you report is necessarily correct,
> > but it could be: ESC and RET are both characters and keys.  In the
> > character context, ESC and RET are correct, while in the key context,
> > `<ESC>' and `<SPC>' are correct (the latter comes from @key, and I
> > don't remember now whether @key produces the quotes in addition to
> > <..>).
> 
> I don't have the Texinfo sources.
> 
> I'm just an Emacs user reporting what seems to be an Emacs bug - in Info.

You are more than "just a user", Drew, let's be honest.

Anyway, at least provide these quotes with context.  Grepping through
Info files for "<SPC>" and the likes is no fun.  Since you already
look at the surrounding text, pasting it into the bug report should
be easy.

> For my part, I was referring to (or trying to refer to) passages that talk about
> keys, not characters. To me, key sequences should be wrapped in `...', even when
> they have <...>. To me, the key sequence should be written `<SPC>' even if the
> character is written SPC.

We use <ESC> and such likes for keyboard keys that are labeled with
more than a single character.  The issue here is to prevent confusion
on the reader's part between a single key labeled "ESC" and a sequence
of 3 keys E, S, C.

When a key is labeled with a single character, this confusion cannot
happen, so <..> is not used in that case, because it would just make
the reading harder with no good reason.

Likewise, key sequences such as C-k are not single keys, you actually
use 2 or more keys to type them.  So <..> is inappropriate in that
context as well.

Thus, single keys and key sequences get different markup.

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

> > > Please show here the Texinfo sources,
> Anyway, at least provide these quotes with context.

I don't have the context anymore, beyond what I originally reported:

emacs -Q
C-h r
g keys

That provides the context of at least one node that appears to have problematic
occurrences. (See also bug #3508, which identified other such contexts.)

> Grepping through Info files for "<SPC>" and the likes is no fun.

... for anyone. Likewise, C-s searching for "<[-_a-zA-Z]+>" or some such.

> > For my part, I was referring to (or trying to refer to) passages
> > that talk about keys, not characters. To me, key sequences
> > should be wrapped in `...', even when they have <...>. To me,
> > the key sequence should be written `<SPC>' even if the
> > character is written SPC.
> 
> We use <ESC> and such likes for keyboard keys that are labeled with
> more than a single character.

You know the conventions we use better than I, Eli.

For my part, there is a difference between three things:

1. character: ESC, SPC
2. physical keyboard key (e.g. labeled): Esc, Page Up
  (not sure how Emacs denotes these)
3. key sequence: `<ESC>', `<SPC>', `<prior>'

What I'm referring to is #3. I believe that was the sense intended in the doc
here. It is the sense that is meant in most occurrences in the doc, in any case.
I have no problem with #1 and #2 being written without `...'.

It is cases of #3 that I'm concerned about. If you look at node `Keys', for
instance, I believe that the occurrences of <ESC> should really be `<ESC>',
since they refer to key sequences, not to characters or physical keys.

[I wouldn't propose changing notations now, but I will point out that if we used
a very different notation for each of #1, 2, 3 there might be less confusion.
For instance, if we used `<space>' and `<escape>' for key sequences (as we do
for `<prior>'), Esc, Page Up, and Space Bar for key names, and SPC and ESC for
characters. Or some other such more obvious difference.]

> The issue here is to prevent confusion
> on the reader's part between a single key labeled "ESC" and a sequence
> of 3 keys E, S, C.

If you mean the physical key labeled "Esc" or "Escape", then I think we write
that as ESC. If you mean the key sequence (i.e. hitting that physical key), then
I think we write that `<ESC>'. If you mean the key sequence of hitting the keys
E, S, C, in order, then I think we write that `E S C'. But again, you're the
expert here, not I.

I'm just pointing out that there seem to be places where we mean the key
sequence `<ESC>', `<RET>' etc. but we have (mistakenly) written the key name
ESC, RET etc.

Or else we have written (incorrectly, IMO) the hybrid form <ESC>, <RET>, when we
mean the key sequence. See bug #3508, for instance:

DA>>> Similarly, <SPC> should be `<SPC>'.
DA>>> Similarly, <TAB> should be `<TAB>' (in node CDLaTeX mode).
  
CY>> This is not necessary.  With few exceptions, we leave don't 
CY>> enclose @key in @kbd if it's the only key in the key sequence.
 
DA> I don't think that's true. We write `i', not i, for command 
DA> `Info-index'. That's the general notation rule, and we 
DA> respect it generally.

I think that what Yidong is saying is wrong, but that's my opinion - I can't
speak for what the established convention is. The convention _should_ be
consistent, IMO: _always_ use `...' for a key sequence. 

There is enough confusion between #1, 2, and 3 (above) due to similar names
(char ESC, physical key ESC, key sequence ESC), without using a hybrid notation
that encourages further confusion.

> When a key is labeled with a single character, this confusion cannot
> happen, so <..> is not used in that case, because it would just make
> the reading harder with no good reason.

Even for a key labeled with a single character, we generally do (and always
should IMO) denote the key sequence using `...': `g', not g for
`Info-goto-node'.

> Likewise, key sequences such as C-k are not single keys, you actually
> use 2 or more keys to type them.  So <..> is inappropriate in that
> context as well.

Sure, but for the key sequence, we wrap with `...': `C-k', `<prior>', `<ESC>'.

> Thus, single keys and key sequences get different markup.

When you say "key" there is an ambiguity. You could be referring to the physical
key (e.g. labeled "Page Up") or to the key sequence - the act of hitting the
physical key. 

Yes, it's handy to sometimes use "keys" as a shortcut for "key sequences" - I
don't have a problem with that generally. But in a context where we might be
talking also about physical keys (or about characters), we need to carefully
distinguish. Distinct notation helps distinguish.

bug#3516: 23.0.94; function key names in Info

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> We see things like <F1>, <F2>, <RET>, and <ESC> without single
> quotes. Similarly, in other parts of the manual.
>
> Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?

That might be argued, but the difference you're seeing is the difference
between these two markups:

@kbd{C-h}
@key{F1}

So I think this is done on purpose, and isn't a bug.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: Lars Magne Ingebrigtsen <larsi@gnus.org>
> Date: Tue, 12 Jul 2011 14:47:09 +0200
> Cc: 3516@debbugs.gnu.org
> 
> "Drew Adams" <drew.adams@oracle.com> writes:
> 
> > We see things like <F1>, <F2>, <RET>, and <ESC> without single
> > quotes. Similarly, in other parts of the manual.
> >
> > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'?
> 
> That might be argued, but the difference you're seeing is the difference
> between these two markups:
> 
> @kbd{C-h}
> @key{F1}

Yes, that's true.  "@key{F1}" in Texinfo produces "<F1>" in Info,
without the single quotes.  In the printed output it produces
something resembling a keyboard key with a label on it.  Taking these
in quotes would be wrong, e.g. because then "@kbd{C-x @key{RET}}"
would produce `C-x `<RET>'' with nested quotes which looks ugly.

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

> "@key{F1}" in Texinfo produces "<F1>" in Info,
> without the single quotes.  In the printed output it produces
> something resembling a keyboard key with a label on it.  Taking these
> in quotes would be wrong, e.g. because then "@kbd{C-x @key{RET}}"
> would produce `C-x `<RET>'' with nested quotes which looks ugly.

What you describe is an implementation problem (Texinfo, Info).

What I describe is from a user point of view: the resulting appearance in the
Info manual.

No one is suggesting that `C-x `<RET>'' should be used.
The point is that `<RET>' should be used.

The entire key sequence - whatever that key sequence is, should be in quotes,
consistently, to indicate a key sequence.  `C-x <RET>' and `<RET>' both
correspond to the same convention: put the sequence of keys in quotes.

We don't write just i - we write `i' when we want to refer to the key sequence
consisting of just the i key.  And we write `C-x i' when we want to refer to the
sequence of the C-x key followed by the i key.

And we write `C-x <RET>' to refer to the sequence of the C-x key followed by the
<RET> key.  Why should we write <RET> for the key sequence `<RET>'?

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <3516@debbugs.gnu.org>
> Date: Tue, 12 Jul 2011 09:38:24 -0700
> 
> > "@key{F1}" in Texinfo produces "<F1>" in Info,
> > without the single quotes.  In the printed output it produces
> > something resembling a keyboard key with a label on it.  Taking these
> > in quotes would be wrong, e.g. because then "@kbd{C-x @key{RET}}"
> > would produce `C-x `<RET>'' with nested quotes which looks ugly.
> 
> What you describe is an implementation problem (Texinfo, Info).

Actually, no: _you_ are talking about implementation.

There are no quotes in the manual sources here, there are 2 different
markups: @kbd and @key.  They are different because they express two
different entities: characters typed by the user on the keyboard as
opposed to a single special key named by its label.  The quotes in one
of the cases are the Info way of _implementing_ the @kbd markup.  Note
that the printed manual doesn't have these quotes, because there @kbd
produces slanted typeface that stands out without any need to quote
it.  Likewise with the other formats supported by the Texinfo package.
Only the Info and the plain text formats use quotes -- it's their
_implementation_ of the @kbd markup.

> What I describe is from a user point of view: the resulting appearance in the
> Info manual.

There's nothing wrong with the appearance.

> The point is that `<RET>' should be used.

According to you.  According to 25-year long practice of writing GNU
manuals, practice that is codified in the Texinfo manual (which is a
de-facto standard for writing GNU documentation), @key{RET} should be
used, and in Info it produces <RET> without quotes.

If you want to request a change in the _implementation_ of @key in the
Info format, the place to request that is in the Texinfo mailing list,
not here.

> The entire key sequence - whatever that key sequence is, should be in quotes,
> consistently, to indicate a key sequence.  `C-x <RET>' and `<RET>' both
> correspond to the same convention: put the sequence of keys in quotes.

<RET> is not a key sequence, it's a single key named by its label.

Again, the distinction between @kbd and @key is very basic.  If you
disagree with it, at least accept that this is widely used practice in
GNU documentation and is explicitly described in the Texinfo manual.

IOW, this is how the GNU project documents its software, whether you
like it or not.  And no amount of bugs filed against Emacs will be
able to change that.

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

> > > "@key{F1}" in Texinfo produces "<F1>" in Info,
> > > without the single quotes.  In the printed output it produces
> > > something resembling a keyboard key with a label on it.  
> > > Taking these in quotes would be wrong, e.g. because then
> > > "@kbd{C-x @key{RET}}" would produce `C-x `<RET>'' with nested
> > > quotes which looks ugly.
> > 
> > What you describe is an implementation problem (Texinfo, Info).
> 
> Actually, no: _you_ are talking about implementation.

No.  I am talking only about the appearance in Info.

> There are no quotes in the manual sources here, there are 2 different
> markups: @kbd and @key.  They are different because they express two
> different entities: characters typed by the user on the keyboard as
> opposed to a single special key named by its label.

And the cases I referred to were about _key sequences_, not key names.

If @kbd is what you use to represent a key sequence, that is, a sequence of
input events, then presumably it should be @kbd that is used in the cases I'm
referring to.  I don't know or care about the proper Texinfo
implementation/representation in order to get the correct Info representation,
but you seem to be saying that @kbd is what should be used for key sequences: a
sequence of chars typed by the user.

I am not speaking about references to the _name_ of the key.  I made that clear
from the beginning.  In those contexts <RET> would be appropriate.

I am speaking about references to the key sequence `<RET>', that is, to the
_use_ of the key.

And yes, a single key press, whether `<RET>' or `M-a' or `a', is a key
_sequence_ as much as is the doubleton sequence `C-x <RET>'.

> The quotes in one of the cases are the Info way of _implementing_
> the @kbd markup.  Note that the printed manual doesn't have these
> quotes, because there @kbd produces slanted typeface that stands
> out without any need to quote it.  Likewise with the other formats
> supported by the Texinfo package.  Only the Info and the plain text
> formats use quotes -- it's their _implementation_ of the @kbd markup.

I am concerned only with the appearance in Info, as I've made clear several
times.  I do not know or care how it is implemented.  I also do not care here
how it appears in other media - this bug report is only about Info.

> > What I describe is from a user point of view: the resulting 
> > appearance in the Info manual.
> 
> There's nothing wrong with the appearance.

It is inconsistent for the doubleton key sequence `C-x <RET>' and the singleton
key sequence `M-a' to be represented using quotes, but not the singleton key
sequence `<RET>'.

> > The point is that `<RET>' should be used.
> 
> According to you.  According to 25-year long practice of writing GNU
> manuals, practice that is codified in the Texinfo manual (which is a
> de-facto standard for writing GNU documentation), @key{RET} should be
> used, and in Info it produces <RET> without quotes.

You alone are talking about @key.  From what you've said above about it, the
occurrences I'm talking about should presumably use @kbd (?).

But I do not pretend to say how you should write it in Texinfo.  I'm only
speaking to how it is represented in the final, Info, result.

> If you want to request a change in the _implementation_ of @key in the
> Info format, the place to request that is in the Texinfo mailing list,
> not here.

It is only you who are speaking about the implementation and Texinfo.  I've been
trying to draw your attention to the appearance in the Info manual, but you keep
descending into Texinfo.

> > The entire key sequence - whatever that key sequence is, 
> > should be in quotes, consistently, to indicate a key sequence.
> > `C-x <RET>' and `<RET>' both correspond to the same convention:
> > put the sequence of keys in quotes.
> 
> <RET> is not a key sequence,

The return key, when expressed in terms of input events (that is, pressing the
return key), is a _key sequence_.  In that context it should be written as a key
sequence: `<RET>'.

When talking only about the _name_ of the return key (and not _use_ of the key
that is named), we should write <RET>.

Any number of keys can constitute a key sequence, including a single key.  We
can write `a b c' and we can write `a'; `C-x a' and `M-a' and `a'.  Or as the
Emacs manual (node `Keys') says:

 A "key sequence", or "key" for short, is a sequence of
 one or more input events that is meaningful as a unit.

NB: _one_ or more, not two or more.  Throughout Emacs and Emacs Lisp, a key
sequence can have _one_ or more keys.  There is nothing new or shocking about
this.

When expressed as a sequence of input events, a single key press is a key
sequence.  This is as true of the sequence `<RET>' as it is of the sequence `a'.

> it's a single key named by its label.

The return key is named by its label <RET>, just as the A key is named by its
label A.  When expressed as a key sequence these should be written `<RET>' and
`A'.  I am not talking about the name of the key; I'm talking about representing
the key as _used_ (or bound), i.e., as a key sequence.

> Again, the distinction between @kbd and @key is very basic.

Please speak in terms of Info and not Texinfo.

Better yet, speak in terms of (a) representation of a key sequence (a sequence
of input events) vs (b) names of keys.

We can speak about the name of a single key, and we can speak about a single key
as a singleton sequence of input events.  It is the latter I'm concerned about -
I have no problem with our writing <RET> (without quotes) when we are referring
to the name of the key and not to use of the key (an input event).

> If you disagree with it, at least accept that this is widely used practice in
> GNU documentation and is explicitly described in the Texinfo manual.
> 
> IOW, this is how the GNU project documents its software, whether you
> like it or not.  And no amount of bugs filed against Emacs will be
> able to change that.

No one is trying to change any of the things you mention.

The point is to write `<RET>' when we mean about _use_ of the return key, that
is, when referring to the key _as a key sequence_ (input event).

The singleton key sequence `<RET>' should be denoted the same way we denote the
doubleton key sequence `C-x <RET>' and the singleton key sequences `M-a' and
`a'.  We should use the same quoting convention, consistently, regardless of
which keys are in a key sequence and regardless of whether it is a singleton or
longer.

This should be a no-brainer, but you are making a big deal out of it.

See, for example, the Emacs manual, node `User Input':

 you can enter `M-a' by typing `<ESC> a'.
 You can enter `C-M-a' by typing `<ESC> C-a'.

Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a.

Other occurrences of <ESC> in the same paragraph refer to the key name: no
single quotes.  That is all correct, IMO.  Similarly, the singleton key sequence
`M-a' is correctly written using quotes.

What I am saying is that, just as we write `<ESC> a' here, so should we write
`C-x <RET>'.  And when referring to a single-key sequence, `<RET>' and `<ESC>'.

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <larsi@gnus.org>, <3516@debbugs.gnu.org>
> Date: Tue, 12 Jul 2011 13:04:14 -0700
> 
> > > What you describe is an implementation problem (Texinfo, Info).
> > 
> > Actually, no: _you_ are talking about implementation.
> 
> No.  I am talking only about the appearance in Info.

The appearance in Info _is_ implementation.

> And the cases I referred to were about _key sequences_, not key names.

Go back and re-read your report.  Then look up the corresponding
portions of the manual, and you will see that <RET>, <F1> etc. are
used in the context that names keys by their names.

If you are saying that sometimes <..> is used where we talk about
keyboard input, then please point out specific instances where that
happens, instead of making a general observation.  As a general
observation, what you say is incorrect.

> If @kbd is what you use to represent a key sequence, that is, a sequence of
> input events, then presumably it should be @kbd that is used in the cases I'm
> referring to.

Which cases, specifically?  Your reference is to an entire node.

> I am not speaking about references to the _name_ of the key.  I made that clear
> from the beginning.

You made nothing clear about that, till now.

> In those contexts <RET> would be appropriate.

Thank you!  We have hope!

> I am speaking about references to the key sequence `<RET>', that is, to the
> _use_ of the key.

"use" is a grey area.  What about the following sentence:

  To end a line, press the <RET> key.

?  Are we naming a key by its label or are we talking about a "key
sequence"?

> > > The point is that `<RET>' should be used.
> > 
> > According to you.  According to 25-year long practice of writing GNU
> > manuals, practice that is codified in the Texinfo manual (which is a
> > de-facto standard for writing GNU documentation), @key{RET} should be
> > used, and in Info it produces <RET> without quotes.
> 
> You alone are talking about @key.  From what you've said above about it, the
> occurrences I'm talking about should presumably use @kbd (?).

@kbd{@key{..}}

> But I do not pretend to say how you should write it in Texinfo.  I'm only
> speaking to how it is represented in the final, Info, result.

If you don't understand Texinfo and don't care about the other output
formats, your report is not of much use, because changes to the manual
_must_ consider all supported forms of output.

> The return key is named by its label <RET>, just as the A key is named by its
> label A.

Not "just".  There's a fundamental difference: "A" is a key and a
character; <RET> is "just" a key.

> > Again, the distinction between @kbd and @key is very basic.
> 
> Please speak in terms of Info and not Texinfo.

No.

> This should be a no-brainer, but you are making a big deal out of it.

Yeah, right.  _I_ am making a big deal.

>  you can enter `M-a' by typing `<ESC> a'.
>  You can enter `C-M-a' by typing `<ESC> C-a'.
> 
> Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a.

When it's clearly part of a sequence of inputs, yes.

> Other occurrences of <ESC> in the same paragraph refer to the key name: no
> single quotes.  That is all correct, IMO.  Similarly, the singleton key sequence
> `M-a' is correctly written using quotes.
> 
> What I am saying is that, just as we write `<ESC> a' here, so should we write
> `C-x <RET>'.  And when referring to a single-key sequence, `<RET>' and `<ESC>'.

Exactly where?  Be specific, if you want any result other than
"wontfix".

bug#3516: 23.0.94; function key names in Info

[Drew Adams]

> > > > What you describe is an implementation problem (Texinfo, Info).
> > > 
> > > Actually, no: _you_ are talking about implementation.
> > 
> > No.  I am talking only about the appearance in Info.
> 
> The appearance in Info _is_ implementation.

When you look at it only as an implementor, perhaps.

Try to take an Info reader point of view.

> > I am not speaking about references to the _name_ of the key.
> > I made that clear from the beginning.
> 
> You made nothing clear about that, till now.

Yes, I did, by speaking about "key sequence".

> > I am speaking about references to the key sequence `<RET>', 
> > that is, to the _use_ of the key.
> 
> "use" is a grey area.  What about the following sentence:
> 
>   To end a line, press the <RET> key.

It's fine, as shorthand for "press the key named <RET>".
<RET> is the name of the key.

But it is also fine to write "press `<RET>'".  Here we are using the name to
refer to the key sequence, that is, the key.  We are saying press the key.  We
are saying the same thing as "press the key named <RET>".

IOW, if we refer to that key-pressing action using the Emacs key-sequence
notation, we say "press `<RET>'" or similar.

`<RET>' refers to using the key named <RET> in an input sequence.

> Are we naming a key by its label or are we talking about a "key
> sequence"?

See above.  We can say either.  It depends whether what is important is the key
sequence or the name of the key.  If we want to talk about the name, then <RET>;
if we want to talk about the input (key) sequence then `<RET>'.

> If you don't understand Texinfo and don't care about the other output
> formats, your report is not of much use, because changes to the manual
> _must_ consider all supported forms of output.

You consider them, then.  I reported the bug.  I'm not proposing what internal
coding to fix it with, i.e., to get the proper appearance in Info.

> >  you can enter `M-a' by typing `<ESC> a'.
> >  You can enter `C-M-a' by typing `<ESC> C-a'.
> > 
> > Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a.
> 
> When it's clearly part of a sequence of inputs, yes.

Thank you.  Now please go DTRT.  That's what this bug report is about.

In Emacs we have a conventional way to represent an input sequence of key
presses (and other input events, including mouse clicks etc.): we put the key
names, in order, between single quotes: `...'.

We call such an input sequence a "key sequence".  We speak of a key sequence
whenever we refer to such an input sequence, including in the context of key
bindings: "this command is bound to the key sequence `M-x'."

This is as true for a key named <RET> as it is for any other key.  When
referring to it in the context of a key sequence it should be between single
quotes.

bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <larsi@gnus.org>, <3516@debbugs.gnu.org>
> Date: Tue, 12 Jul 2011 14:03:19 -0700
> 
> >   To end a line, press the <RET> key.
> 
> It's fine, as shorthand for "press the key named <RET>".
> <RET> is the name of the key.
> 
> But it is also fine to write "press `<RET>'".

So we are taking the former view and using just <RET>.

> Thank you.  Now please go DTRT.  That's what this bug report is about.

I don't see any bug, so there's no RTTD except leave the bug report
closed.  I asked for specific pointers to where the usage is
incorrect, but you declined (in so many words).  So that's it.