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

[Eli Zaretskii]

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

Thanks.