bug#1111: describe-key's key notation display inconsistency

bug#1111: describe-key's key notation display inconsistency

[xah lee]

When doing a describe-key on C-<backspace>, emacs prints <C- 
backspace> instead. Similar for any other special key whose macro  
notation are bracketed by angle brackets. e.g. <down>, <F6>,  
<return>, <kp-1>, etc. Where, emacs puts the entire thing inside  
angle brackets instead of the more traditional of modifier followed  
by dash followed by key name.

Although these are identical as far as kbd function is concerned, but  
wouldn't it be more intuitively consistent by using C-<key> instead  
of <C-key>?

Thanks.

   Xah
∑ http://xahlee.org/

☄

bug#1111: describe-key's key notation display inconsistency

[Stefan Kangas]

xah lee <xah@xahlee.org> writes:

> When doing a describe-key on C-<backspace>, emacs prints <C-
> backspace> instead. Similar for any other special key whose macro notation are
> bracketed by angle brackets. e.g. <down>, <F6>, <return>, <kp-1>, etc. Where,
> emacs puts the entire thing inside angle brackets instead of the more
> traditional of modifier followed by dash followed by key name.
>
> Although these are identical as far as kbd function is concerned, but wouldn't
> it be more intuitively consistent by using C-<key> instead of <C-key>?

Would anyone else want to weigh in on this old wishlist item?  Is this a
good idea, even if it is very minor, or should we close this as wontfix?

FWIW, I personally don't mind either way.

Thanks,
Stefan Kangas

bug#1111: describe-key's key notation display inconsistency

[Drew Adams]

> > When doing a describe-key on C-<backspace>, emacs prints <C-
> > backspace> instead. Similar for any other special key whose macro
> > notation are bracketed by angle brackets. e.g. <down>, <F6>,
> > <return>, <kp-1>, etc. Where, emacs puts the entire thing inside
> > angle brackets instead of the more traditional of modifier
> > followed by dash followed by key name.
> >
> > Although these are identical as far as kbd function is concerned,
> > but wouldn't it be more intuitively consistent by using C-<key>
> > instead of <C-key>?
> 
> Would anyone else want to weigh in on this old wishlist item?  Is this
> a good idea, even if it is very minor, or should we close this as
> wontfix?
> 
> FWIW, I personally don't mind either way.

Dunno whether this is really weighing in, but...

I've said before (not in this thread, most likely)
that I think that the Emacs manuals should use the
exact same notation that Emacs itself uses
interactively.

That means the manuals should use <C-return>, not
C-<return>.  But they don't.

As for "the more traditional": we shouldn't care.
(I don't.)  Emacs should do what is best for Emacs.

The consistency we should look for is local, i.e.,
within Emacs.  Eli has defended the use of the
C-<return> notation in the manuals, so so be it:
we'll continue to live with that inconsistency
(relatively minor) in how Emacs talks about itself.

But at least interactively we should remain
consistent.  And there can be arguments in favor of
the <C-return> notation, even beyond the obvious
one that Emacs has long, long used it, so that
there is now no doubt code that expects and depends
on it.

My vote is not to change from <C-return> to
C-<return>.  (And my vote would be to always use
the former, even in the manuals.)

---

FWIW, I've also argued that we do not need
angle-bracket notation at all.  We can drop it and
still be completely unambiguous and consistent.
(I proposed this long ago, but it was rejected.)

IOW, instead of `C-x M-<delete>' we can use just
`C-x M-delete' - always.

I even have a library, `naked.el', that lets you
optionally get the angle-bracket-less notation,
except for places I can't control(e.g. C code):

https://www.emacswiki.org/emacs/NaKeD

bug#1111: describe-key's key notation display inconsistency

[Noam Postavsky]

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

> I've said before (not in this thread, most likely)
> that I think that the Emacs manuals should use the
> exact same notation that Emacs itself uses
> interactively.
>
> That means the manuals should use <C-return>, not
> C-<return>.  But they don't.

Having Emacs print C-<return>, as suggested in the OP, would also solve
the consistency, yes?  I think it's a bit more readable, so I would be
in favour of that.

> ---
>
> FWIW, I've also argued that we do not need
> angle-bracket notation at all.  We can drop it and
> still be completely unambiguous and consistent.

That assumes all function key names are longer than one letter, right?

bug#1111: describe-key's key notation display inconsistency

[Drew Adams]

> > I've said before (not in this thread, most likely)
> > that I think that the Emacs manuals should use the
> > exact same notation that Emacs itself uses
> > interactively.
> >
> > That means the manuals should use <C-return>, not
> > C-<return>.  But they don't.
> 
> Having Emacs print C-<return>, as suggested in the OP,
> would also solve the consistency, yes?

Yes, of course.  At the cost of a lot of code
changes, not to mention user mind changes. ;-)

[We could also change Elisp to use only
M-expressions, not S-expressions (sexps) -
e.g. car('(1 2)) instead of (car '(1 2)), to
more closely fit syntax expectations outside
Lisp.]

https://en.wikipedia.org/wiki/M-expression

> I think it's a bit more readable, so I would
> be in favour of that.

To me it's less readable, but tastes vary.

`C-x <right>' is noticeably different from
`<C-right>'.

`C-x <right>' is not so noticeably different
from `C-<right> (to me, at least).

---

> > FWIW, I've also argued that we do not need
> > angle-bracket notation at all.  We can drop
> > it and still be completely unambiguous and
> > consistent.
> 
> That assumes all function key names are longer
> than one letter, right?

Yes.  But we already have the symbol for the
corresponding event, which presumably has the
same potential problem.

E.g., the event that corresponds to the key
described as `<right>' is the symbol `right'
(no angle brackets).  The event that
corresponds to the key described as `<M-F3>'
is `M-f3'.

Presumably the key described as `<M-D>' (or
`M-<D>', per Xah), where `<D>' is a function
key, would correspond to event `M-d', which
might already be problematic (no?).

(And we would anyway distinguish function
keys `<D>' and `<M-D>' via the bracket syntax,
as `[M-d]'.  It would only be the (proposed)
standard key description where naked `d' and
`M-d' could be ambiguous.)

We could also make it explicitly conventional
for a function key (including a fake function
key, for a menu item) to have more than one
character.  We have no such convention, AFAICT,
but have you ever come across a single-char
function-key name?

Or we could just leave `d' ambiguous, in the
rare case that there might be an `d' function
key as well as the `d' character key.

I'd bet that there are no such anomalous
function keys today (or in the past).  Do you
know of any?  And do we even know whether all
of Emacs works OK with such a function key?

Anyway, going naked ain't gonna happen.
That's been made clear.

BTW, since Emacs 22, `single-key-description'
takes an optional arg NO-ANGLES, which does
what you might expect.  Here is the reason
given (in (elisp) `Describing Characters'):

 If the optional argument NO-ANGLES is non-'nil',
 the angle brackets around function keys and
 event symbols are omitted; this is for
 compatibility with old versions of Emacs which
 didn't use the brackets.

(I don't think angle brackets are ever used
around event symbols, so I'm guessing that
"and event symbols" is wrong, there.)

bug#1111: describe-key's key notation display inconsistency

[Noam Postavsky]

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

>> > I've said before (not in this thread, most likely)
>> > that I think that the Emacs manuals should use the
>> > exact same notation that Emacs itself uses
>> > interactively.
>> >
>> > That means the manuals should use <C-return>, not
>> > C-<return>.  But they don't.
>> 
>> Having Emacs print C-<return>, as suggested in the OP,
>> would also solve the consistency, yes?
>
> Yes, of course.  At the cost of a lot of code
> changes, not to mention user mind changes. ;-)

I don't think the code change would be that large (but we've not seen a
patch yet).

>> > FWIW, I've also argued that we do not need
>> > angle-bracket notation at all.  We can drop
>> > it and still be completely unambiguous and
>> > consistent.
>> 
>> That assumes all function key names are longer
>> than one letter, right?
>
> Yes
[...]
> Presumably the key described as `<M-D>' (or
> `M-<D>', per Xah), where `<D>' is a function
> key, would correspond to event `M-d', which
> might already be problematic (no?).

I don't think so, (kbd "M-d") => [?\M-d], but (kbd "<M-D>") => [M-D].

> but have you ever come across a single-char
> function-key name?

No (and I didn't mean to say that assuming all function key names are
multi-character is unreasonable).

bug#1111: describe-key's key notation display inconsistency

[Drew Adams]

> > Presumably the key described as `<M-D>' (or
> > `M-<D>', per Xah), where `<D>' is a function
> > key, would correspond to event `M-d', which
> > might already be problematic (no?).
> 
> I don't think so, (kbd "M-d") => [?\M-d],
> but (kbd "<M-D>") => [M-D].

I'm talking about the _event_.  The value
of the event is a symbol.  In both cases
(I think) it would be the symbol `M-d'.

> > but have you ever come across a single-char
> > function-key name?
> 
> No (and I didn't mean to say that assuming
> all function key names are multi-character
> is unreasonable).

(I didn't expect that you did mean that.)

My point (in this tangent discussion) is that
it is possible to drop the angle brackets.
And the result would be a lot less noise.

But unless we also added a convention such as
no single-char function-key names, there could
be some rare ambiguity.

One way to avoid that rare case of ambiguity
would be to use angle brackets only for the
case of single-char names.

bug#1111: describe-key's key notation display inconsistency

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:
>
> The value of the event is a symbol.

I don't understand where you're getting that idea from.

(info "(elisp) Keyboard Events"):

    There are two kinds of input you can get from the keyboard: ordinary
    keys, and function keys.  Ordinary keys correspond to (possibly
    modified) characters; the events they generate are represented in Lisp
    as characters.

bug#1111: describe-key's key notation display inconsistency

[Drew Adams]

> > The value of the event is a symbol.
> 
> I don't understand where you're getting that idea from.
> (info "(elisp) Keyboard Events"):
> 
>   There are two kinds of input you can get from the keyboard:
>   ordinary keys, and function keys.  Ordinary keys correspond to 
>   (possibly modified) characters; the events they generate are 
>   represented in Lisp as characters.

We're not talking about ordinary keys.  We're
talking about function keys.  They're not
represented as characters.  They're represented
as Lisp symbols.

(elisp) `Function Keys':

  Function keys are represented in Emacs Lisp as
  symbols; the symbol's name is the function key's
  label, in lower case.

  For example, pressing a key labeled <F1> generates
  an input event represented by the symbol 'f1'.

(Note: not the symbol `<f1>' - see my statement that
I think the doc that says that the angle brackets
are part of the event name is incorrect, per this
doc passage.)

  The event type of a function key event is the event
  symbol itself.  See Classifying Events.

  ... the symbol for the key <F3> with <META> held
  down is `M-f3'.

Similarly, in (elisp) `Classifying Events' it talks
about event types also being symbols:

  ... the event type for a function key symbol is
  the symbol itself.

"Function key symbol", there seems to be the
symbol talked about in `Function Keys'.  So function
keys and their events and the event types are all
"represented in Emacs Lisp by symbols".  Likewise,
event modifiers are symbols.

bug#1111: describe-key's key notation display inconsistency

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Cc: xah lee <xah@xahlee.org>, 1111@debbugs.gnu.org,
>  Stefan Kangas <stefan@marxist.se>
> 
> (elisp) `Function Keys':
> 
>   Function keys are represented in Emacs Lisp as
>   symbols; the symbol's name is the function key's
>   label, in lower case.
> 
>   For example, pressing a key labeled <F1> generates
>   an input event represented by the symbol 'f1'.
> 
> (Note: not the symbol `<f1>' - see my statement that
> I think the doc that says that the angle brackets
> are part of the event name is incorrect, per this
> doc passage.)

You are mixing keys with events produced by those keys and with the
description of those keys and events.  They are all different.

bug#1111: describe-key's key notation display inconsistency

[Stefan Kangas]

tags 1111 fixed
close 1111 28.1
thanks

xah lee <xah@xahlee.org> writes:

> When doing a describe-key on C-<backspace>, emacs prints <C-backspace>
> instead. Similar for any other special key whose macro notation are bracketed by
> angle brackets. e.g. <down>, <F6>, <return>, <kp-1>, etc. Where, emacs puts the
> entire thing inside angle brackets instead of the more traditional of modifier
> followed by dash followed by key name.
>
> Although these are identical as far as kbd function is concerned, but wouldn't
> it be more intuitively consistent by using C-<key> instead of <C-key>?

This is now the case in Emacs 28, from NEWS:

    ** Modifiers now go outside angle brackets in pretty-printed key bindings.
    For example, 'RET' with Control and Meta modifiers is now shown as
    'C-M-<return>' instead of '<C-M-return>'.  Either variant can be used
    as input; functions such as 'kbd' and 'read-kbd-macro' accept both
    styles as equivalent (they have done so for a long time).

I'm therefore closing this bug report.

bug#1111: [External] : bug#1111: describe-key's key notation display inconsistency

[Drew Adams]

> This is now the case in Emacs 28, from NEWS:
> 
>     ** Modifiers now go outside angle brackets in pretty-printed key
>     bindings.
>     For example, 'RET' with Control and Meta modifiers is now shown as
>     'C-M-<return>' instead of '<C-M-return>'.  Either variant can be
>     used
>     as input; functions such as 'kbd' and 'read-kbd-macro' accept both
>     styles as equivalent (they have done so for a long time).

Unfortunate.

Should have instead made the manuals consistent
with the way Emacs has (forever) talked about
itself, if consistency was the aim.  (Internal
/ local consistency is always more important
than global consistency.

This will require at least some 3rd-party docs
(HTML, wiki, plain-text, whatever) to change,
where such bindings are explicit (not via
\\[...]).

And as I mentioned in this thread, it will
lead users to misread and confuse things like
`C-x <right>' with `C-<right>'.  There's
no such problem with `<C-right>'.
___

Beyond that, if the change is what was requested
by the OP, then it's a change in *Help* (perhaps
among other things).  And yet that's not even
mentioned in the NEWS.

What does "in pretty-printed key bindings" refer
to?  Users will rightfully wonder.  The manuals?
(No, they already used C-<right>.)  Output of
`pp' commands?  Messages?  Byte-compiler
warnings?  All of the above?  None of the above?

bug#1111: describe-key's key notation display inconsistency

[Xah Lee]

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

thank you.

On Fri, Sep 24, 2021 at 3:00 PM Stefan Kangas <stefan@marxist.se> wrote:

> tags 1111 fixed
> close 1111 28.1
> thanks
>
> xah lee <xah@xahlee.org> writes:
>
> > When doing a describe-key on C-<backspace>, emacs prints <C-backspace>
> > instead. Similar for any other special key whose macro notation are
> bracketed by
> > angle brackets. e.g. <down>, <F6>, <return>, <kp-1>, etc. Where, emacs
> puts the
> > entire thing inside angle brackets instead of the more traditional of
> modifier
> > followed by dash followed by key name.
> >
> > Although these are identical as far as kbd function is concerned, but
> wouldn't
> > it be more intuitively consistent by using C-<key> instead of <C-key>?
>
> This is now the case in Emacs 28, from NEWS:
>
>     ** Modifiers now go outside angle brackets in pretty-printed key
> bindings.
>     For example, 'RET' with Control and Meta modifiers is now shown as
>     'C-M-<return>' instead of '<C-M-return>'.  Either variant can be used
>     as input; functions such as 'kbd' and 'read-kbd-macro' accept both
>     styles as equivalent (they have done so for a long time).
>
> I'm therefore closing this bug report.
>

[-- Attachment #2: Type: text/html, Size: 1739 bytes --]