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

Message received at 67700 <at> debbugs.gnu.org:

Received: (at 67700) by debbugs.gnu.org; 8 Dec 2023 06:27:36 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Dec 08 01:27:35 2023
Received: from localhost ([127.0.0.1]:43642 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rBUKl-00079V-9b
	for submit <at> debbugs.gnu.org; Fri, 08 Dec 2023 01:27:35 -0500
Received: from eggs.gnu.org ([2001:470:142:3::10]:33472)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <eliz@HIDDEN>) id 1rBUKj-00079H-G2
 for 67700 <at> debbugs.gnu.org; Fri, 08 Dec 2023 01:27:33 -0500
Received: from fencepost.gnu.org ([2001:470:142:3::e])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <eliz@HIDDEN>)
 id 1rBUKR-0006Za-C8; Fri, 08 Dec 2023 01:27:15 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org;
 s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date:
 mime-version; bh=xKTfMOApw1rjuPe1bn0ybjdjIg6FzJL7itW7IiteAco=; b=anJXEMM8VR8m
 eCi6FBykaK61Y8yb9dA0+vO7aHHHUMtVliTJQuMe/EgDIYocBAUhFYnJPs86sZxzuwUxoW1/vEjPX
 sfVpIZVGj1C3haYBr96QeMjy8dDtbpRFBw8LzVQAJnsLpf4VIrzUPN5YDU+qPcQwoYpByB4A0PYjf
 jNPKCETn4bmcPfO0nC5J6tIgIeQyPnbJ+Ck+tQJOOqBzRtOVq8MK/3gkIg7Y8k0YldCL9rVN7iWL/
 GU1ArMFL1VeS/5ezIm+UdOyPTdYlwmh/N7n16W/Y7frM75/y1XBZtDl5UrupNXHhkkCJ5dtK4iyn4
 s5kfyfgfqIel9vI2ZANhIQ==;
Date: Fri, 08 Dec 2023 08:27:29 +0200
Message-Id: <83msul1a5q.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Howard Melman <hmelman@HIDDEN>
In-Reply-To: <5320A546-FCE6-4131-B3F9-AFC8513D034D@HIDDEN> (message from
 Howard Melman on Thu, 7 Dec 2023 16:53:34 -0500)
Subject: Re: bug#67700: 29.1; Minor keymap- commands documention issues
References: <5320A546-FCE6-4131-B3F9-AFC8513D034D@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 67700
Cc: 67700 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

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

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 7 Dec 2023 21:54:14 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Dec 07 16:54:14 2023
Received: from localhost ([127.0.0.1]:43279 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rBMJy-0004c6-9N
	for submit <at> debbugs.gnu.org; Thu, 07 Dec 2023 16:54:14 -0500
Received: from lists.gnu.org ([2001:470:142::17]:37988)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <hmelman@HIDDEN>) id 1rBMJs-0004bg-Uy
 for submit <at> debbugs.gnu.org; Thu, 07 Dec 2023 16:54:13 -0500
Received: from eggs.gnu.org ([2001:470:142:3::10])
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <hmelman@HIDDEN>) id 1rBMJa-0004Ov-R2
 for bug-gnu-emacs@HIDDEN; Thu, 07 Dec 2023 16:53:50 -0500
Received: from mail-yw1-x1130.google.com ([2607:f8b0:4864:20::1130])
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
 (Exim 4.90_1) (envelope-from <hmelman@HIDDEN>) id 1rBMJZ-0006yw-BG
 for bug-gnu-emacs@HIDDEN; Thu, 07 Dec 2023 16:53:50 -0500
Received: by mail-yw1-x1130.google.com with SMTP id
 00721157ae682-5b383b4184fso12087077b3.1
 for <bug-gnu-emacs@HIDDEN>; Thu, 07 Dec 2023 13:53:48 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=gmail.com; s=20230601; t=1701986026; x=1702590826; darn=gnu.org;
 h=to:date:message-id:subject:mime-version:content-transfer-encoding
 :from:from:to:cc:subject:date:message-id:reply-to;
 bh=RGQIdosTCtsTEXCLR1cYpW95dLj++u69fKYWl9zENjY=;
 b=e/HpvPG4g2k0a5byj59Dxkv+Cou/yab2F5jWmqn/2n4pyHtXCZAZji3X0+w0x6SQh0
 f2b35IJpj3bk8vEaXA5UjdMz8xpMhBz2Famd6+QKNLXZicR4aYYBZeYNMCJj3ufemjRj
 cGng4YRIBcu08PgU0rQF4AlPLtaDqX5HIlh51v1ek/PNUlaC0nPLi0wMC+ZAmRygK46z
 8Y51FWj4sNW18ZW2k1TDIVn/Avnw/OmGAN9AYf6rxT540bgX5YYImWLF0ZWBlPYzvsZE
 tL1BxHWFR1Qc4fkZ3ZzyF+mCljdIsJHLerL2nPOQ5X8Slpc2zeBkgZSvDeqq/VetQasU
 C8rw==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
 d=1e100.net; s=20230601; t=1701986026; x=1702590826;
 h=to:date:message-id:subject:mime-version:content-transfer-encoding
 :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to;
 bh=RGQIdosTCtsTEXCLR1cYpW95dLj++u69fKYWl9zENjY=;
 b=TlKUT7N9CYIqcvO6l0q57MYqx4gNnoyq9p2ajRowXwgOCxSTX2sDS/fjeWTJj1D/lz
 6JgA7LR2f8lOpOOzlq6ir/LIy49qNOcQP63fxKKiSS63O4X+i80LR9Mye/6YKpUmuZLd
 fHpMYsCy1ndXpG5qlSkz9p0YbMjLavF+IfcscOShhT7badEcJyq0SXIWCSoPzkSue/Yn
 OyizuxAHBYWDt0h7Zjyp7YQvwnP6VStHOVlTqqIF+cQSe0gY7DmP/SDwF0nlt0O1PPHo
 +gPpBpGpfdntBlmXn4RBBNua8EQxo2YYcXT1h8kv4kCufeW5dc8fXoPgTP7c36qDPr24
 B3ew==
X-Gm-Message-State: AOJu0YzIeqaQtC7vHzyU8ef/mpSG6eWuvAcnGdqGEWWvPwpRTTIDFL7/
 r8EZKTPMPMHMV45Oujh570ee8Un+7Ag=
X-Google-Smtp-Source: AGHT+IFz94fEPmkZzT2tszQ6R5xqIb/wxsfhjKGPwPEhnTSt7c9kXWwMFtLHxhNgfyedhfPNCQnYbQ==
X-Received: by 2002:a81:9f11:0:b0:5d7:1940:7d8f with SMTP id
 s17-20020a819f11000000b005d719407d8fmr2919271ywn.102.1701986026278; 
 Thu, 07 Dec 2023 13:53:46 -0800 (PST)
Received: from smtpclient.apple (pool-108-26-231-137.bstnma.fios.verizon.net.
 [108.26.231.137]) by smtp.gmail.com with ESMTPSA id
 p15-20020a0cf68f000000b0066d12d1351fsm226650qvn.143.2023.12.07.13.53.45
 for <bug-gnu-emacs@HIDDEN>
 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128);
 Thu, 07 Dec 2023 13:53:45 -0800 (PST)
From: Howard Melman <hmelman@HIDDEN>
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: 7bit
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3731.700.6\))
Subject: 29.1; Minor keymap- commands documention issues
Message-Id: <5320A546-FCE6-4131-B3F9-AFC8513D034D@HIDDEN>
Date: Thu, 7 Dec 2023 16:53:34 -0500
To: GNU Emacs <bug-gnu-emacs@HIDDEN>
X-Mailer: Apple Mail (2.3731.700.6)
Received-SPF: pass client-ip=2607:f8b0:4864:20::1130;
 envelope-from=hmelman@HIDDEN; helo=mail-yw1-x1130.google.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001,
 RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.0 (/)

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