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

From: Eli Zaretskii <[email-masked]>
Date: Fri, 08 Dec 2023 08:27:29 +0200

> From: Howard Melman <[email-masked]>
> 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.