Update doc of local-map and keymap text properties.

diff --git a/lispref/text.texi b/lispref/text.texi
index 5f5b33f81776f4923e0fa99c06f08a7c931c1988..5d8809b215d95c25d9fe436105ff9ff1e8e3c2a7 100644 (file)
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -2714,21 +2714,22 @@ You can alter the way help text is displayed by setting the variable
 This feature is used in the mode line and for other active text.  It is
 available starting in Emacs 21.
 
-@item local-map
-@cindex keymap of character
-@kindex local-map @r{(text property)}
-You can specify a different keymap for some of the text in a buffer by
-means of the @code{local-map} property.  The property's value for the
-character after point, if non-@code{nil}, is used for key lookup instead
-of the buffer's local map.  If the property value is a symbol, the
-symbol's function definition is used as the keymap.  @xref{Active
-Keymaps}.
-
 @item keymap
+@cindex keymap of character
 @kindex keymap @r{(text 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.
+The @code{keymap} property specifies an additional keymap for
+commands.  The property's value for the character after point, if
+non-@code{nil}, is used for key lookup before the buffer's local map.
+(For mouse clicks, the @code{keymap} property of the character clicked
+on is the one used.)  If the property value is a symbol, the symbol's
+function definition is used as the keymap.  @xref{Active Keymaps}.
+
+@item local-map
+@kindex local-map @r{(text property)}
+This property specifies a keymap to use @emph{instead of} the buffer's
+local map.  If the property value is a symbol, the symbol's function
+definition is used as the keymap.  For most purposes (perhaps all
+purposes), the @code{keymap} is superior.
 
 @item syntax-table
 The @code{syntax-table} property overrides what the syntax table says