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

Previous Next

Full log

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.