bug-gnu-emacs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#3516: 23.0.94; function key names in Info


From: Drew Adams
Subject: bug#3516: 23.0.94; function key names in Info
Date: Tue, 12 Jul 2011 13:04:14 -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.

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






reply via email to

[Prev in Thread] Current Thread [Next in Thread]