bug#52821: Should "(elisp) Keymaps" describe key sequences first?

bug#52821: Should "(elisp) Keymaps" describe key sequences first?

[Stefan Kangas]

Now that we promote the new keymap-* functions, does it really make
sense to start the section (info "(elisp) Keymaps") with a description
of key sequences?

This seems to now be considered more of an internal detail, and the
thing that should be exposed to (new) ELisp code is rather the new key
description format accepted by `key-valid-p'.

I'm thinking it should be moved further down, perhaps in a section next
to this one:

* Low-Level Key Binding::       Legacy key syntax description.

There is a good description on the "new" key format in
(info "(elisp) Changing Key Bindings").  Perhaps it should
be moved up instead?

bug#52821: Should "(elisp) Keymaps" describe key sequences first?

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Now that we promote the new keymap-* functions, does it really make
  > sense to start the section (info "(elisp) Keymaps") with a description
  > of key sequences?

  > This seems to now be considered more of an internal detail,

A key sequence is a Lisp object, and it's not internal -- quite a few
programs operate on them.

The description in that node is confused between describing the
Lisp object itself and describing its printed representation.
Perhaps this node should describe the Lisp object format
and the issue of printing and inputting them should be elsewhere.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#52821: Should "(elisp) Keymaps" describe key sequences first?

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Now that we promote the new keymap-* functions, does it really make
> sense to start the section (info "(elisp) Keymaps") with a description
> of key sequences?
>
> This seems to now be considered more of an internal detail, and the
> thing that should be exposed to (new) ELisp code is rather the new key
> description format accepted by `key-valid-p'.
>
> I'm thinking it should be moved further down, perhaps in a section next
> to this one:
>
> * Low-Level Key Binding::       Legacy key syntax description.

Yes, sounds good to me.

> There is a good description on the "new" key format in
> (info "(elisp) Changing Key Bindings").  Perhaps it should
> be moved up instead?

Yup.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no