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

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

[Drew Adams]

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'

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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/

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

[Drew Adams]

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