GNU bug report logs - #15993
24.3.50; doc of `set-temporary-overlay-map' - explain "used only once"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15993 in the body.
You can then email your comments to 15993 AT debbugs.gnu.org in the normal way.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once"
Date: Thu, 28 Nov 2013 12:37:42 -0800 (PST)

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=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15993 <at> debbugs.gnu.org
Subject: Re: bug#15993: 24.3.50;
 doc of `set-temporary-overlay-map' - explain "used only once"
Date: Fri, 07 Feb 2014 19:06:53 -0800

Drew Adams <drew.adams <at> oracle.com> 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/

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15993 <at> debbugs.gnu.org
Subject: RE: bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain
 "used only once"
Date: Sat, 8 Feb 2014 15:00:16 -0800 (PST)

> > 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.

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'.
| 
| (set-temporary-overlay-map MAP &optional KEEP-PRED ON-EXIT)
| 
| 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.
| 
| 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.
| 
| Optional ON-EXIT argument is a function that is called after the
| deactivation of MAP.
`----

Previous Next

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