all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once"
@ 2013-11-28 20:37 Drew Adams
  2014-02-08  3:06 ` Lars Ingebrigtsen
  0 siblings, 1 reply; 3+ messages in thread
From: Drew Adams @ 2013-11-28 20:37 UTC (permalink / raw)
  To: 15993

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'





^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2014-02-08 23:00 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2013-11-28 20:37 bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once" Drew Adams
2014-02-08  3:06 ` Lars Ingebrigtsen
2014-02-08 23:00   ` Drew Adams

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.