bug#3516: 23.0.94; function key names in Info

["Drew Adams" <drew.adams@oracle.com>]

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