bug#67700: 29.1; Minor keymap- commands documention issues

bug#67700: 29.1; Minor keymap- commands documention issues

[Howard Melman]

Is there an advantage to calls to keymap-set (and
keymap-global-set) using #' for the command definition?
IIUC it is a compiler hint that the symbol is a
function. Most examples in the emacs manual (e.g., 50.3.6
Rebinding Keys in Your Init File) just use ' not #', but the
50.3.7 Modifier Keys section says:

    (keymap-global-set "C-S-n" #'previous-line)

Grepping the emacs sources shows both styles are used in
code.  If #' is preferred with the keymap commands, the
examples should use it and if not, IMHO it's worth
mentioning in the manual that using #' is unnecessary as
this was a common question of newbies copying config
snippets before the keymap commands.


Also, I found the following idiom useful in my init for
defining several bindings at once in an existing map:

	(define-keymap :keymap (current-global-map)
	  "M-u"     #'upcase-dwim		; was upcase-word
	  "M-l"     #'downcase-dwim		; was downcase-word
	  "M-/"     #'hippie-expand		; was dabbrev-expand
	  "M-$"     #'lookup-word-at-point)

I didn't see anywhere in the emacs manual on keybinding
customization an example of how to define multiple bindings
at once in the same keymap.  This terse style is IMHO
cleaner than repeated calls to keymap-global-set.

When reading the docs on the new keymap commands, how to do
this on an existing keymap wasn't obvious to me.  It is
mentioned in the elisp manual but just in the description of
:keymap which is the 3rd keyword in a list of 6, without any
example.

I think it would be useful to have an example of doing this
some place (maybe section 50.3.6 in the emacs manual); that
is calling define-keymap with :keymap and perhaps
specifically using (current-global-map) as that wasn't on my
radar before either.


In GNU Emacs 29.1 (build 1, x86_64-apple-darwin21.6.0,
Carbon Version 165 AppKit 2113.6) of 2023-08-08 built on
Mac-1691500888998.local

-- 

Howard

bug#67700: 29.1; Minor keymap- commands documention issues

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Thu, 7 Dec 2023 16:53:34 -0500
> 
> Is there an advantage to calls to keymap-set (and
> keymap-global-set) using #' for the command definition?
> IIUC it is a compiler hint that the symbol is a
> function. Most examples in the emacs manual (e.g., 50.3.6
> Rebinding Keys in Your Init File) just use ' not #', but the
> 50.3.7 Modifier Keys section says:
> 
>     (keymap-global-set "C-S-n" #'previous-line)
> 
> Grepping the emacs sources shows both styles are used in
> code.  If #' is preferred with the keymap commands, the
> examples should use it and if not, IMHO it's worth
> mentioning in the manual that using #' is unnecessary as
> this was a common question of newbies copying config
> snippets before the keymap commands.
> 
> 
> Also, I found the following idiom useful in my init for
> defining several bindings at once in an existing map:
> 
> 	(define-keymap :keymap (current-global-map)
> 	  "M-u"     #'upcase-dwim		; was upcase-word
> 	  "M-l"     #'downcase-dwim		; was downcase-word
> 	  "M-/"     #'hippie-expand		; was dabbrev-expand
> 	  "M-$"     #'lookup-word-at-point)
> 
> I didn't see anywhere in the emacs manual on keybinding
> customization an example of how to define multiple bindings
> at once in the same keymap.  This terse style is IMHO
> cleaner than repeated calls to keymap-global-set.
> 
> When reading the docs on the new keymap commands, how to do
> this on an existing keymap wasn't obvious to me.  It is
> mentioned in the elisp manual but just in the description of
> :keymap which is the 3rd keyword in a list of 6, without any
> example.
> 
> I think it would be useful to have an example of doing this
> some place (maybe section 50.3.6 in the emacs manual); that
> is calling define-keymap with :keymap and perhaps
> specifically using (current-global-map) as that wasn't on my
> radar before either.

Thanks.  Patches for the manual to improve these parts will be very
welcome.