From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once" Date: Thu, 28 Nov 2013 12:37:42 -0800 (PST) Message-ID: <3f303fda-e66b-4d9c-a1a7-da7d9950d09d@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1385671162 4341 80.91.229.3 (28 Nov 2013 20:39:22 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 28 Nov 2013 20:39:22 +0000 (UTC) To: 15993@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Nov 28 21:39:26 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Vm8Mv-0002dz-OB for geb-bug-gnu-emacs@m.gmane.org; Thu, 28 Nov 2013 21:39:25 +0100 Original-Received: from localhost ([::1]:44012 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8Mv-0005Yv-7M for geb-bug-gnu-emacs@m.gmane.org; Thu, 28 Nov 2013 15:39:25 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42193) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8Mj-0005Wo-3T for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:39:23 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Vm8MZ-0006l3-0j for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:39:13 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:35203) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Vm8MY-0006kz-Tp for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:39:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Vm8MY-0003as-Ga for bug-gnu-emacs@gnu.org; Thu, 28 Nov 2013 15:39:02 -0500 X-Loop: help-debbugs@gnu.org 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: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.138567110513763 (code B ref -1); Thu, 28 Nov 2013 20:39:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Nov 2013 20:38:25 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:81059 Archived-At: 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'