bug#74999: [PATCH v2] Recommend `keymap-set' instead of `define-key' in emacs lisp intro

[Hong Xu]

On 2024-12-20 Fri 23:19 GMT-08, Eli Zaretskii <eliz@gnu.org> wrote:

>> From: Hong Xu <hong@topbug.net>
>> Date: Fri, 20 Dec 2024 13:42:29 -0800
>> 
>> -Mode-specific keymaps are bound using the @code{define-key} function,
>> +Mode-specific keymaps are bound using the @code{keymap-set} function,
>>  which takes a specific keymap as an argument, as well as the key and
>> -the command.  For example, my @file{.emacs} file contains the
>> -following expression to bind the @code{texinfo-insert-@@group} command
>> -to @kbd{C-c C-c g}:
>> +the command.  For example, the following expression binds the
>> +@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}:
>> +
>> +@smallexample
>> +@group
>> +(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
>> +@end group
>> +@end smallexample
>> +
>> +While you are encouraged to use @code{keymap-set}, you likely would
>> +encounter @code{define-key} in various places. @code{define-key} is an
>> +older function to create keymaps, and is now considered legacy.
>
> This should say that historically, Emacs used 'define-key', and
> therefore you are likely to see 'define-key' in various places etc.
> In addition "older function" is not really accurate: 'keymap-set'
> calls 'define-key' internally, so 'define-key' will not disappear from
> Emacs any time soon.  We just prefer using 'keymap-set' in Lisp
> programs because it is higher-level.  So instead of saying "older
> function", I think we should say "more low-level function".
>
> Also, please make sure to leave two spaces between sentences, per our
> conventions.
>
>>                                                             The
>> +above key map can be rewritten in @code{define-key} as:
>
> Not "key map", but "key binding".  The example doesn't show a complete
> key map, it only shows a single binding within a key map.  Since this
> is an introductory manual, we must be very accurate and clear in our
> text, to avoid confusing newcomers to Lisp, who are probably confused
> already to begin with...
>

I agree, please see my follow-up patch.

-- 
Thanks,
Hong