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'