Subject: Re: bug#74999: [PATCH v4] Use `keymap*-set' over `global-set-key'/`define-key' in elisp intro

From: Eli Zaretskii <[email-masked]>
Date: Sat, 28 Dec 2024 14:17:28 +0200

> From: Hong Xu <[email-masked]>
> Date: Thu, 26 Dec 2024 13:46:39 -0800
> 
> * doc/lispintro/emacs-lisp-intro.texi (Key Bindings): Since
> `global-set-key' and `define-key' are considered legacy, we encourage
> `keymap-global-set' and `keymap-set' now.
> ---
>  doc/lispintro/emacs-lisp-intro.texi | 119 +++++++++++++++++++---------
>  1 file changed, 81 insertions(+), 38 deletions(-)

Thanks, I have a few minor comments:

>  @cindex Setting a key globally
> -@cindex Global set key
> +@cindex Keymap global set
>  @cindex Key setting globally
> -@findex global-set-key

Please add index entries for the new APIs, but do not remove the index
entries for old ones.  Readers could still need to look up the old
interfaces via index search.

> -@findex global-unset-key
> +@findex keymap-global-unset

Same here.

> +@subsection Legacy Global Key Binding Commands
> +
> +@findex global-set-key
> +@cindex Global set key
> +Historically, keys are bound globally using a lower-level function,
> +@code{global-set-key}, which is now considered legacy.  While you are
> +encouraged to use @code{keymap-global-set}, you likely would encounter
> +@code{global-set-key} in various places.  The first example can be
> +rewritten using @code{global-set-key} as:
> +
> +@smallexample
> +@group
> +(global-set-key "\C-cw" 'compare-windows)
> +@end group
> +@end smallexample

The text says "first example", but which example is that?  There are
no examples in this subsection.

> +Historically, keys are unbound globally using a lower-function,
> +@code{global-unset-key}, which is now considered legacy.  Its key
> +binding format follows that of @code{global-set-key}.  The above key
> +unbinding example can be rewritten as:

Same here: "the above key unbinding example" refers to an example in a
different subsection.

Thanks.