GNU bug report logs - #67700
29.1; Minor keymap- commands documention issues

Previous Next

To reply to this bug, email your comments to 67700 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Howard Melman <hmelman <at> gmail.com>
To: GNU Emacs <bug-gnu-emacs <at> gnu.org>
Subject: 29.1; Minor keymap- commands documention issues
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.


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

Message #8 received at 67700 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 67700 <at> debbugs.gnu.org
Subject: Re: bug#67700: 29.1; Minor keymap- commands documention issues
Date: Fri, 08 Dec 2023 08:27:29 +0200

> From: Howard Melman <hmelman <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.