bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii <eliz@gnu.org>]

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