On 2024-12-28 Sat 04:17 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Hong Xu <hong@topbug.net>
>> 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.

I moved these two indices to the legacy subsection, which is now the
place that describes these functions.

>
>> +@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.

The updated patch now adds an "in this section" qualifier. Please see
the attachment.