bug#3516: 23.0.94; function key names in Info

[Eli Zaretskii <eliz@gnu.org>]

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