RE: [External] : New key binding syntax

[Drew Adams]

>> Have a look at the kbd-valid-p doc string on the 
>> current trunk for a definition.
> 
> I've included that text below, because now is the time
> for people to look at and comment on it.
> 
> Should the syntax Emacs adopts for the next 20 years be
> this one?  This one with some changes?  Any other proposal?
> 
> If we use this syntax, the text we use to define it in
> the Emacs Lisp Ref Manual should cover valid cases not
> mentioned in this text.  We don't use them in normal
> Emacs bindings, but they are valid so they should be
> documented.


You didn't get much of a response to your request
for opinions about this.  FWIW, here's my opinion
on the key-sequence description syntax we should use.

___

This is about use cases where we now use `kbd'.  This
is typically about using (kbd ...) as input to things
like `define-key'.

This is not particularly about how some explanatory
text in a manual, for example, can refer to things like
inputs in general or about message outputs.  For that,
I think the currently used representation is fine.
That can of course include the use of key descriptions,
such as are accepted by `kbd'.  It also includes text
such as `M-x some-command'.

And it even includes informal text such as "Type M-x
foobar RET".  (Notice that "foobar" here informally
stands for typing the sequence "f SPC o SPC o SPC b SPC
a SPC r", but "RET" stands for hitting just that key,
not for hitting the keys "R", "E", and "T".)

I say this deciding about key-description syntax is not
about that, in particular, to distinguish the use of
whitespace.  Informal description of user input and
output messages is something different from, and more
inclusive and forgiving than, the precise syntax of
key-sequence descriptions.

For simplicity I'll generally refer to the
key-description syntax I prefer as "kbd" syntax,
because it's essentially what `kbd' accepts.

Some (Stefan K in particular) have pointed out that the
current implementation of `kbd' accepts some
seldom-used or outlier syntax possibilities, and `kbd'
might have some bugs or undesirable features.

I don't include those in the syntax I prefer.  If we
ever get to that point, that is, if we ever get general
agreement on the "normal", syntax that `kbd' accepts as
what we want for the future, then at that point we can
discuss any of the odd or arcane possibilities that
`kbd' also accepts.

___


1. Whitespace should be allowed arbitrarily for
separation in the key-description syntax.  I believe
this is already the case (at least for space chars),
but in any case it should be.

You should be able to use "a    b  c", or "a b
c" (including the newline), or "  a b  c   ", or any
other syntax where any number of SPC, TAB, and newline
chars separate keys in a key sequence.  (No, I wouldn't
allow unusual Unicode whitespace chars - no need; these
are just separators, for our convenience.)

IOW, I don't agree with Lars's preference of allowing
only a single SPC char as separator; I agree with John
Yates here.  And I'd go beyond SPC to allow newline and
TAB, but that's not important - just a nice-to-have /
why-not.

2. A space char in a key sequence should be represented
as SPC in a key description, not as a literal space
char.  I see _no_ advantage to having space chars
represent themselves literally, as opposed to using the
name of the key that's associated with, and by default
inserts, that char: (kbd "SPC").

Same for newline (C-j) and TAB (C-i) keys. To represent
a TAB key, use (kbd "TAB") or (kbd "C-i"); to represent
a newline, use C-j: (kbd "C-j").  We'd just be asking
for trouble, and confusing users _more_ (not less), if
we started using " " instead of "SPC" - without gaining
anything.

(And yes, the key `<tab>' is different from the key
`TAB', though sometimes the one gets translated to the
other for binding lookup.)

(Whether and how weallow unicode, octal, or other
representations for chars in key descriptions is
another question.  I don't have an answer/preference
for that now, but maybe it should be discussed at some
point.)

3. Personally, I don't feel a need to allow the
argument to `kbd' to be used on its own (e.g., passed
to `define-key" or its replacement), in place of using
(kbd ARG) - let alone feel a need to prescribe that.

I don't see that as helping anyone.  Just as for using
" " instead of "SPC", I expect that doing that just
asks for trouble and sows confusion, without any gain.
This is just a guess; I could maybe be convinced
otherwise, but so far I haven't seen any good argument.

4. I agree that if `kbd' has some anomalies, as Stefan
K pointed out, we can remove them from any new,
replacement syntax we define.

I don't care much whether we use a new function (e.g.
`key') or we just change `kbd' itself, purifying it of
anomalies.  The former is maybe easier and cleaner, to
let `kbd' continue to go its merry way for backward
compatibility.

5. I don't think we should impose a single ordering of
modifiers.  But I do think we should have a convention
that specifies a preferred order.

IOW, let's separate what you _can_ use (any modifier
order) from what we recommend you _do_ use.  For the
recommended order, let's stick with what we've already
recommended - which should be the same order that Emacs
itself uses in its Help output.  E.g., `C-M-', not
`M-C-'.  But again, this isn't very important - it's
just a convention that makes things more consistent,
hence easier to read and digest.

6. The correspondence between the syntax you pass to
`kbd' and the syntax that Emacs Help uses is very
important, IMO.  Emacs and users (including users of
Elisp) should talk about keys using the same syntax,
as much as possible.

7. I'm in favor of letting `kbd' and Help descriptions
drop the use of angle brackets altogether.  I've done
that, and I haven't encountered any problems or
contradictions from doing it.  `kbd' (or `key' or
whatever) can and should accept both angle-bracketed
and "naked" syntax (no brackets), with no difference in
behavior.  Again, I've been doing this for decades now.

FWIW (but I don't care how Emacs itself does it), I use
function `naked' instead of function `kbd', and
`naked-key-description' instead of `key-description'.
Emacs itself wouldn't need two sets of functions.

Function `naked' indifferently accepts either naked or
angle-bracketed syntax as input.

(To reproduce Emacs bug #12535 faithfully (!) it also
accepts an optional Boolean arg ANGLES, which forces
the bugged behavior, e.g., makes the input "M-<TAB>"
output [M-TAB] instead of the correct output
[134217737].)

Other NaKeD functions likewise accept an optional
ANGLES arg.  With non-nil arg, `naked-key-description'
does just what `key-description' does (otherwise it
outputs naked key descriptions).  Likewise
`naked-read-kbd-macro' and `naked-edmacro-parse-keys':
an optional arg gives the current bracketed Emacs
behavior.

But my point here is that Emacs itself does not need
angle-bracket syntax - at all.  (Eli claims otherwise,
but I've seen no counter-example so far.)  That noise
was introduced gratuitously in Emacs 21, I believe.  

`C-x toto' unequivocally means the same thing as `C-x
<toto>'.  And the few ASCII control chars with names
that we accept (RET, SPC, ESC, etc.) don't invalidate
this proposition.  (And yes, bug #12535 is a bug.)

#7 here is apparently heretical, and I don't expect it
to be accepted.  But I feel obliged to mention it once
more, since the question has been raised of the syntax
we want for key descriptions.  There really is no need
for angle brackets.  Really.  So Occam says drop 'em.
(Or show a real case where they're actually needed.)

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

Code:
 https://www.emacswiki.org/emacs/download/naked.el

___

As for the new syntax proposal that RMS asked about,
from the `kbd-valid-p' doc string: seems like confusion
of use and mention.

(I don't know what `kbd-valid-p' is really for, but I'm
guessing it's for testing the validity of a key
description, e.g. what `kbd' or its replacement should
accept as a valid arg, i.e., as an arg that validly
describes a possible key sequence.)

It confuses statements of what a key sequence is with
what the syntax of a key(-sequence) description is,
i.e., what constitutes a "valid key sequence" (which is
a sequence of keys) versus what constitutes a valid
key-sequence description for use in code and Help (e.g.
as arg to `kbd').

It's OK in the doc to talk about the "key sequence `C-x
C-f'", because there we're _using_ the term "key
sequence" to talk about a key sequence, which itself is
represented by the description `C-x C-f'.  We're not
talking about the text/syntax "C-x C-f" there; we're
talking about the sequence of keys that that
description represents.

But when we're talking about defining/specifying valid
syntax for key descriptions, we shouldn't say we're
talking about defining which _key sequences_ are valid.

\"S o m\" is _not_ a key sequence.  It's not a
"sequence of the keys 'S', 'o' and 'm'".  It's
presumably (a proposal for) a valid key-sequence
description string.

___

One opinion.  I agree with Richard that we should hear
more opinions.  Let's get the right dough before baking.