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

* bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once"
  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
  0 siblings, 1 reply; 3+ messages in thread
From: Lars Ingebrigtsen @ 2014-02-08  3:06 UTC (permalink / raw)
  To: Drew Adams; +Cc: 15993

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/





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

* bug#15993: 24.3.50; doc of `set-temporary-overlay-map' - explain "used only once"
  2014-02-08  3:06 ` Lars Ingebrigtsen
@ 2014-02-08 23:00   ` Drew Adams
  0 siblings, 0 replies; 3+ messages in thread
From: Drew Adams @ 2014-02-08 23:00 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 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?
> 
> 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.
`----





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