bug#13219: 24.3.50; missing `...' in Emacs manual

bug#13219: 24.3.50; missing `...' in Emacs manual

[Drew Adams]

There are still some missing `...' in the Emacs manual.  See node
`Keys', for instance.  Each key sequence is correctly quoted there,
except for these: `<F1>', `<F2>', `<ESC>'.  `<ESC> C-h' is
correctly quoted, but `<ESC>' is not quoted, though it should be.
 
 
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-13 on ODIEONE
Bzr revision: 111211 eggert@cs.ucla.edu-20121213021749-eyqqen0ewhn2hogq
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include -Wall -Wextra -Wno-sign-compare
 -Wno-type-limits -Wno-missing-field-initializers -Wno-pointer-sign
 -Wdeclaration-after-statement --ldflags -LC:/Devel/emacs/build/lib'
 

bug#13219: 24.3.50; missing `...' in Emacs manual

[Chong Yidong]

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

> There are still some missing `...' in the Emacs manual.  See node
> `Keys', for instance.  Each key sequence is correctly quoted there,
> except for these: `<F1>', `<F2>', `<ESC>'.  `<ESC> C-h' is
> correctly quoted, but `<ESC>' is not quoted, though it should be.

It is the convention in the manual not to insert `..' around single
function keys which are already printed like <this>.  Not a bug (and no
bike-shedding please).

bug#13219: 24.3.50; missing `...' in Emacs manual

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 1073 bytes --]

> > There are still some missing `...' in the Emacs manual.  See node
> > `Keys', for instance.  Each key sequence is correctly quoted there,
> > except for these: `<F1>', `<F2>', `<ESC>'.  `<ESC> C-h' is
> > correctly quoted, but `<ESC>' is not quoted, though it should be.
> 
> It is the convention in the manual not to insert `..' around single
> function keys which are already printed like <this>.  Not a 
> bug (and no bike-shedding please).

See attached screenshot.  Are you perhaps trying to make a virtue (and a
convention) out of mistake?  Do you honestly think it is more readable to have
these exceptions?

If you want to get rid of unnecessary wrappers, and have consistency at the same
time, then get rid of the angle brackets.  They serve no purpose whatsoever, as
I've demonstrated before (and can again).

I can even give you the code to get rid of them from the product altogether (not
the doc), with the exception of the C code for `substitute-command-keys', which
someone else will need to patch.  Better: I can give you code that makes them
optional.

[-- Attachment #2: throw-unquoted-keys.png --]
[-- Type: image/png, Size: 8647 bytes --]

bug#13219: 24.3.50; missing `...' in Emacs manual

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 21 Dec 2012 00:24:21 -0800
> Cc: 13219@debbugs.gnu.org
> 
> > It is the convention in the manual not to insert `..' around single
> > function keys which are already printed like <this>.  Not a 
> > bug (and no bike-shedding please).
> 
> See attached screenshot.  Are you perhaps trying to make a virtue (and a
> convention) out of mistake?  Do you honestly think it is more readable to have
> these exceptions?

Are you referring to the highlight?  If so, who or what did the
highlighting of `..' strings in that screenshot?  I don't see such
highlighting in "emacs -Q".

We had this argument before.  <FOO> is a name of a single key.  We
don't quote single keys named by their labels, only key sequences.

bug#13219: 24.3.50; missing `...' in Emacs manual

[Drew Adams]

> > > It is the convention in the manual not to insert `..' 
> > > around single function keys which are already printed
> > > like <this>.  Not a bug (and no bike-shedding please).
> > 
> > See attached screenshot.  Are you perhaps trying to make a 
> > virtue (and a convention) out of mistake?  Do you honestly
> > think it is more readable to have these exceptions?
> 
> Are you referring to the highlight?  If so, who or what did the
> highlighting of `..' strings in that screenshot?  I don't see such
> highlighting in "emacs -Q".

No, I was not referring to the highlight (which comes from my code).  The
highlighting just points out more clearly the exceptional treatment (kludge)
when denoting single-key sequences of "function keys".

(BTW, <ESC>, <RET>, <SPC>, <DEL>, <TAB> etc. are _not_ "function keys".)

> We had this argument before.  <FOO> is a name of a single key.  We
> don't quote single keys named by their labels, only key sequences.

Right, you don't.  That just says that you have implemented the kludge as your
convention.  Repeating what the status quo is is not an argument in favor of it.

Except that you _do_, for most keys: `a', `@', `8' are all single keys named by
their labels.  Or if you want to use angle brackets or some other convention to
distinguish physical keys from key sequences, then do it consistently for both
<ESC> and <a> - versus key sequences `ESC' and `a'.

So you don't quote single-key key sequences for certain keys.  That's true.  But
you should.  The status quote is a hodge-podge.

A key sequence of a single key is a key sequence.  And it should be handled the
same as any other key sequence wrt notation, whether the key is `f' or `f1' (or
`<f1>' if you insist on the useless angle brackets).  Whether it is `E' or `ESC'
(or `<ESC>'...).

The current policy is in fact "We don't quote single-key key sequences ...
unless they are keys like `a', `8', `*', etc., IOW most keys."  We don't ...
except we do most of the time.

It's a dumb policy, IMHO.  You use one kind of quotation, `...', to talk about
the `a' key (sequence) and another kind of quotation, <...>, to talk about the
`ESC' key (sequence).

That's totally unnecessarily, confusing, and offends Occam's razor.  But I
understand that you will not be convinced.  As you say, we have had this
discussion before.

And no, this has nothing to do with the difference between a physical key and a
key sequence.  I'm talking about key sequences, which include single-key
sequences such as `a' and `ESC' and `f10'.

We should have a single, consistent notation for all key sequences.  There is no
need for a double standard here, and with no need there is also no reason for
it.

You know full well that there is no ambiguity in using `...' for all key
sequences.  In particular, e.g. (yes, we've been through this before too), `ESC'
is a single-key sequence, `E S C' is a 3-key sequence, and `E SPC S C' is a
4-key sequence.

Today you write <ESC>, `E S C', and `E SPC S C'.  Lose the brackets and get
consistent.  Or as this bug report states, at least get consistent in quoting
all key sequences: `<ESC>', `E S C', `E SPC S C'.

bug#13219: 24.3.50; missing `...' in Emacs manual

[Stephen Berman]

On Fri, 21 Dec 2012 11:22:48 +0200 Eli Zaretskii <eliz@gnu.org> wrote:

>> From: "Drew Adams" <drew.adams@oracle.com>
>> Date: Fri, 21 Dec 2012 00:24:21 -0800
>> Cc: 13219@debbugs.gnu.org
>> 
>> > It is the convention in the manual not to insert `..' around single
>> > function keys which are already printed like <this>.  Not a 
>> > bug (and no bike-shedding please).
>> 
>> See attached screenshot.  Are you perhaps trying to make a virtue (and a
>> convention) out of mistake?  Do you honestly think it is more readable to have
>> these exceptions?
>
> Are you referring to the highlight?  If so, who or what did the
> highlighting of `..' strings in that screenshot?  I don't see such
> highlighting in "emacs -Q".
>
> We had this argument before.  <FOO> is a name of a single key.  We
> don't quote single keys named by their labels, only key sequences.

Actually, the convention appears to be: enclose single keys labels that
are not single characters in angle brackets but quote single keys labels
that are single characters (as well as labels of key sequences);
cf. (emacs) Dired Navigation:

"For extra convenience, <SPC> and `n' in Dired are equivalent to `C-n'."

Steve Berman

bug#13219: 24.3.50; missing `...' in Emacs manual

[Drew Adams]

> Actually, the convention appears to be: enclose single keys 
> labels that are not single characters in angle brackets but
> quote single keys labels that are single characters (as well
> as labels of key sequences);

Yes, and that inconsistency is unnecessary.

My guess is that this double-standard convention was implemented/adopted due to
a misunderstanding of what " " means in key-sequence notation.

" " separates keys of the sequence, nothing more.  It never denotes the space
key, which `SPC' denotes in key sequence notation.

`f 1' means the key sequence of hitting the `f' key followed by hitting the `1'
key.

`f1' means the single-key key sequence of hitting the `f1' key (a function key).

`f SPC 1' means the key sequence of hitting `f' then `SPC then `1'.

There is no good reason to have introduced two kinds of quoting (angle brackets
and `...').  That is, there is no necessity for that.

Function keys and keys such as `ESC' `DEL' are unambiguously denoted using only
`...' syntax.  And it is not too late to get rid of the kludge - or at least
make it optional for those who are hooked on it.