From 9716fedb62698b1f27e51a1dd185a612cbb4963a Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Wed, 19 Jun 2013 09:51:47 -0400 Subject: [PATCH] * doc/lispref/keymaps.texi (Active Keymaps): Fix documentation of set-temporary-overlay-map and overriding-terminal-local-map. * doc/lispref/modes.texi (Mode Line Data, Properties in Mode): Advertise `keymap' rather than `local-map'. --- doc/lispref/ChangeLog | 8 ++++++++ doc/lispref/display.texi | 24 ++++++++++++------------ doc/lispref/keymaps.texi | 11 +++++------ doc/lispref/modes.texi | 6 +++--- 4 files changed, 28 insertions(+), 21 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 8572fbe3e8..65fc76d15f 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,11 @@ +2013-06-19 Stefan Monnier + + * modes.texi (Mode Line Data, Properties in Mode): Advertise `keymap' + rather than `local-map'. + + * keymaps.texi (Active Keymaps): Fix documentation of + set-temporary-overlay-map and overriding-terminal-local-map. + 2013-06-19 Glenn Morris * Makefile.in (dist): Edit more configure variables. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 4ad2289804..34eda6ecd6 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1655,26 +1655,26 @@ if it becomes empty (i.e., if its length becomes zero). If you give an empty overlay a non-@code{nil} @code{evaporate} property, that deletes it immediately. -@item local-map -@cindex keymap of character (and overlays) -@kindex local-map @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. - @item keymap +@cindex keymap of character (and overlays) @kindex keymap @r{(overlay property)} -The @code{keymap} property is similar to @code{local-map} but overrides the -buffer's local map (and the map specified by the @code{local-map} -property) rather than replacing it. +If this property is non-@code{nil}, it specifies a keymap for a portion of the +text. This keymap is used when the character after point is within the +overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}. + +@item local-map +@kindex local-map @r{(overlay property)} +The @code{local-map} property is similar to @code{keymap} but replaces the +buffer's local map rather than augmenting existing keymaps. This also means it +has lower precedence than minor mode keymaps. @end table -The @code{local-map} and @code{keymap} properties do not affect a +The @code{keymap} and @code{local-map} properties do not affect a string displayed by the @code{before-string}, @code{after-string}, or @code{display} properties. This is only relevant for mouse clicks and other mouse events that fall on the string, since point is never on the string. To bind special mouse events for the string, assign it a -@code{local-map} or @code{keymap} text property. @xref{Special +@code{keymap} or @code{local-map} text property. @xref{Special Properties}. @node Finding Overlays diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 822e952ef9..ef02036408 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -663,17 +663,16 @@ additional active keymaps through the variable The highest precedence normal keymap comes from the @code{keymap} text or overlay property. If that is non-@code{nil}, it is the first -keymap to be processed, in normal circumstances. Next comes -any keymap added by the function @code{set-temporary-overlay-map}. -@xref{Controlling Active Maps}. +keymap to be processed, in normal circumstances. However, there are also special ways for programs to substitute other keymaps for some of those. The variable @code{overriding-local-map}, if non-@code{nil}, specifies a keymap that replaces all the usual active keymaps except the global keymap. -Another way to do this is with @code{overriding-terminal-local-map}; -it operates on a per-terminal basis. These variables are documented -below. + +The very highest precedence keymap comes from +@code{overriding-terminal-local-map}; it operates on a per-terminal basis and +is normally used for modal/transient keybindings. @cindex major mode keymap Since every buffer that uses the same major mode normally uses the diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 7d42d2591d..59729380ea 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1800,7 +1800,7 @@ display of the text just as they would text in the buffer. Any characters which have no @code{face} properties are displayed, by default, in the face @code{mode-line} or @code{mode-line-inactive} (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The -@code{help-echo} and @code{local-map} properties in @var{string} have +@code{help-echo} and @code{keymap} properties in @var{string} have special meanings. @xref{Properties in Mode}. @item @var{symbol} @@ -2205,7 +2205,7 @@ The value of @code{global-mode-string}. Certain text properties are meaningful in the mode line. The @code{face} property affects the appearance of text; the @code{help-echo} property associates help strings with the text, and -@code{local-map} can make the text mouse-sensitive. +@code{keymap} can make the text mouse-sensitive. There are four ways to specify text properties for text in the mode line: @@ -2229,7 +2229,7 @@ structure, and make @var{form} evaluate to a string that has a text property. @end enumerate - You can use the @code{local-map} property to specify a keymap. This + You can use the @code{keymap} property to specify a keymap. This keymap only takes real effect for mouse clicks; binding character keys and function keys to it has no effect, since it is impossible to move point into the mode line. -- 2.20.1