From unknown Tue Aug 19 10:02:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once" Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Nov 2013 20:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 15993 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 15993@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.138567110513763 (code B ref -1); Thu, 28 Nov 2013 20:39:02 +0000 Received: (at submit) by debbugs.gnu.org; 28 Nov 2013 20:38:25 +0000 Received: from localhost ([127.0.0.1]:49222 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Vm8Lw-0003Zt-6s for submit@debbugs.gnu.org; Thu, 28 Nov 2013 15:38:24 -0500 Received: from eggs.gnu.org ([208.118.235.92]:40395) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Vm8Lu-0003Zd-63 for submit@debbugs.gnu.org; Thu, 28 Nov 2013 15:38:23 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vm8Le-0006EE-OI for submit@debbugs.gnu.org; Thu, 28 Nov 2013 15:38:16 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_40 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:59178) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8Le-0006EA-LE for submit@debbugs.gnu.org; Thu, 28 Nov 2013 15:38:06 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42066) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8LV-00051d-Sg for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:38:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vm8LN-00069P-8Y for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:37:57 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:46103) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8LN-00069I-1r for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:37:49 -0500 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id rASKblVY012887 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Thu, 28 Nov 2013 20:37:48 GMT Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id rASKbkKF004377 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Thu, 28 Nov 2013 20:37:47 GMT Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id rASKbkvu004372 for ; Thu, 28 Nov 2013 20:37:46 GMT MIME-Version: 1.0 Message-ID: <3f303fda-e66b-4d9c-a1a7-da7d9950d09d@default> Date: Thu, 28 Nov 2013 12:37:42 -0800 (PST) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) This pertains to both the Elisp manual and the doc string. This function puts a keymap in place temporarily, and that keymap overrides most other keymaps. The important question of what "temporarily" means here is not answered by the doc. It says only "Normally, MAP is used only once." A user is left to guess what "used only once" means. Only one occurrence of what? Just say that it is used only for the next key-sequence event, or something similar. Somehow, state that it is (with null KEEP-PRED) in effect only for the next event. For *anything* that "sets" something for only a certain duration, e.g., until some state change, it is important to say what it is that causes the setting to no longer be in effect. It also would not hurt to either describe a typical use case or show a simple example. The uses of this all seem to be similar, but it is not obvious from the description alone what this function is for. In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-11-28 on MW7G474MYRXUPA Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --enable-checking 'CFLAGS=3D-O0 -g3' CPPFLAGS=3D-DGLYPH_DEBUG= =3D1' From unknown Tue Aug 19 10:02:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once" Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 08 Feb 2014 03:09:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15993 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 15993@debbugs.gnu.org Received: via spool by 15993-submit@debbugs.gnu.org id=B15993.139182890317213 (code B ref 15993); Sat, 08 Feb 2014 03:09:01 +0000 Received: (at 15993) by debbugs.gnu.org; 8 Feb 2014 03:08:23 +0000 Received: from localhost ([127.0.0.1]:55751 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WByHG-0004TZ-Lm for submit@debbugs.gnu.org; Fri, 07 Feb 2014 22:08:22 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:41707) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WByHE-0004TN-R5 for 15993@debbugs.gnu.org; Fri, 07 Feb 2014 22:08:21 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1WByGv-0003vC-LV; Sat, 08 Feb 2014 04:08:02 +0100 From: Lars Ingebrigtsen References: <3f303fda-e66b-4d9c-a1a7-da7d9950d09d@default> Date: Fri, 07 Feb 2014 19:06:53 -0800 In-Reply-To: <3f303fda-e66b-4d9c-a1a7-da7d9950d09d@default> (Drew Adams's message of "Thu, 28 Nov 2013 12:37:42 -0800 (PST)") Message-ID: <87ob2i9ub6.fsf@building.gnus.org> User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-MailScanner-ID: 1WByGv-0003vC-LV X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392433682.15275@yF7HcMxic2K0FIF7u8hWDg X-Spam-Status: No X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) Drew Adams writes: > This pertains to both the Elisp manual and the doc string. > > This function puts a keymap in place temporarily, and that keymap > overrides most other keymaps. The important question of what > "temporarily" means here is not answered by the doc. It says only > "Normally, MAP is used only once." A user is left to guess what > "used only once" means. Only one occurrence of what? The doc string now says Set MAP as a temporary keymap taking precedence over other keymaps. Normally, MAP is used only once, to look up the very next key. However, if the optional argument KEEP-PRED is t, MAP stays active if a key from MAP is used. KEEP-PRED can also be a function of no arguments: if it returns non-nil, then MAP stays active. which I think is clear enough. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ From debbugs-submit-bounces@debbugs.gnu.org Fri Feb 07 22:08:25 2014 Received: (at control) by debbugs.gnu.org; 8 Feb 2014 03:08:25 +0000 Received: from localhost ([127.0.0.1]:55754 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WByHJ-0004To-83 for submit@debbugs.gnu.org; Fri, 07 Feb 2014 22:08:25 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:41713) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WByHH-0004Th-H3 for control@debbugs.gnu.org; Fri, 07 Feb 2014 22:08:23 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1WByH1-0003vP-5l for control@debbugs.gnu.org; Sat, 08 Feb 2014 04:08:07 +0100 Date: Fri, 07 Feb 2014 19:06:59 -0800 Message-Id: <87mwi29ub0.fsf@building.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #15993 X-MailScanner-ID: 1WByH1-0003vP-5l X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1392433687.89477@8KcJauov0Sc0XA3nhweuRg X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) close 15993 From unknown Tue Aug 19 10:02:41 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once" Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 08 Feb 2014 23:01:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15993 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Lars Ingebrigtsen Cc: 15993@debbugs.gnu.org Received: via spool by 15993-submit@debbugs.gnu.org id=B15993.1391900426320 (code B ref 15993); Sat, 08 Feb 2014 23:01:01 +0000 Received: (at 15993) by debbugs.gnu.org; 8 Feb 2014 23:00:26 +0000 Received: from localhost ([127.0.0.1]:58329 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCGsr-000055-5W for submit@debbugs.gnu.org; Sat, 08 Feb 2014 18:00:25 -0500 Received: from aserp1040.oracle.com ([141.146.126.69]:50372) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCGso-0008WV-AV for 15993@debbugs.gnu.org; Sat, 08 Feb 2014 18:00:23 -0500 Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by aserp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s18N0Jwc000346 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 8 Feb 2014 23:00:20 GMT Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id s18N0IX7024620 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 8 Feb 2014 23:00:19 GMT Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s18N0Ik6002448; Sat, 8 Feb 2014 23:00:18 GMT MIME-Version: 1.0 Message-ID: <466c1988-c807-45fe-af2e-179333ce9ac9@default> Date: Sat, 8 Feb 2014 15:00:16 -0800 (PST) From: Drew Adams References: <3f303fda-e66b-4d9c-a1a7-da7d9950d09d@default> <87ob2i9ub6.fsf@building.gnus.org> In-Reply-To: <87ob2i9ub6.fsf@building.gnus.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-Spam-Score: -2.8 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.8 (--) > > This pertains to both the Elisp manual and the doc string. > > > > This function puts a keymap in place temporarily, and that keymap > > overrides most other keymaps. The important question of what > > "temporarily" means here is not answered by the doc. It says only > > "Normally, MAP is used only once." A user is left to guess what > > "used only once" means. Only one occurrence of what? >=20 > The doc string now says >=20 > Set MAP as a temporary keymap taking precedence over other keymaps. > Normally, MAP is used only once, to look up the very next key. > However, if the optional argument KEEP-PRED is t, MAP stays > active if a key from MAP is used. KEEP-PRED can also be a > function of no arguments: if it returns non-nil, then MAP stays > active. >=20 > which I think is clear enough. Yes, the bug was fixed. FYI, this was the text from the build where I submitted the bug report: ,---- | set-temporary-overlay-map is a compiled Lisp function in `subr.el'. |=20 | (set-temporary-overlay-map MAP &optional KEEP-PRED ON-EXIT) |=20 | Set MAP as a temporary keymap taking precedence over most other keymaps. | Note that this does NOT take precedence over the "overriding" maps | `overriding-terminal-local-map' and `overriding-local-map' (or the | `keymap' text property). Unlike those maps, if no match for a key is | found in MAP, the normal key lookup sequence then continues. |=20 | Normally, MAP is used only once. If the optional argument | KEEP-PRED is t, MAP stays active if a key from MAP is used. | KEEP-PRED can also be a function of no arguments: if it returns | non-nil then MAP stays active. |=20 | Optional ON-EXIT argument is a function that is called after the | deactivation of MAP. `----