Merged from miles@gnu.org--gnu-2005 (patch 269)

[bpt/emacs.git] / lispref / keymaps.texi

diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index b9227ab..59e2e19 100644 (file)
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/keymaps
 @node Keymaps, Modes, Command Loop, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/keymaps
 @node Keymaps, Modes, Command Loop, Top


@@ -9,7 +10,7 @@
 
   The bindings between input events and commands are recorded in data
 structures called @dfn{keymaps}.  Each binding in a keymap associates
 
   The bindings between input events and commands are recorded in data
 structures called @dfn{keymaps}.  Each binding in a keymap associates

-(or @dfn{binds}) an individual event type either to another keymap or to
+(or @dfn{binds}) an individual event type, either to another keymap or to

 a command.  When an event type is bound to a keymap, that keymap is used
 to look up the next input event; this continues until a command is
 found.  The whole process is called @dfn{key lookup}.
 a command.  When an event type is bound to a keymap, that keymap is used
 to look up the next input event; this continues until a command is
 found.  The whole process is called @dfn{key lookup}.


@@ -27,6 +28,7 @@ found.  The whole process is called @dfn{key lookup}.
 * Key Lookup::                  How extracting elements from keymaps works.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
 * Key Lookup::                  How extracting elements from keymaps works.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.

+* Remapping Commands::          Bindings that translate one command to another.

 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 * Menu Keymaps::               Defining a menu as a keymap.
 * Key Binding Commands::        Interactive interfaces for redefining keys.
 * Scanning Keymaps::            Looking through all keymaps, for printing help.
 * Menu Keymaps::               Defining a menu as a keymap.


@@ -93,6 +95,30 @@ precedence over) the corresponding global bindings.  The minor mode
 keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
 for details.
 
 keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
 for details.
 

+  The Emacs Lisp representation for a key sequence is a string or vector.
+You can enter key sequence constants using the ordinary string or vector
+representation; it is also convenient to use @code{kbd}:
+
+@defmac kbd keyseq-text
+This macro converts the text @var{keyseq-text} (a string constant)
+into a key sequence (a string or vector constant).  The contents
+of @var{keyseq-text} should describe the key sequence using the syntax
+used in this manual.  More precisely, it uses the same syntax that
+Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard
+Macro,,, emacs, The GNU Emacs Manual}).
+
+@example
+(kbd "C-x") @result{} "\C-x"
+(kbd "C-x C-f") @result{} "\C-x\C-f"
+(kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
+(kbd "X") @result{} "X"
+(kbd "RET") @result{} "\^M"
+(kbd "C-c SPC") @result{} "\C-c@ "
+(kbd "<f1> SPC") @result{} [f1 32]
+(kbd "C-M-<down>") @result{} [C-M-down]
+@end example
+@end defmac
+

 @node Format of Keymaps
 @section Format of Keymaps
 @cindex format of keymaps
 @node Format of Keymaps
 @section Format of Keymaps
 @cindex format of keymaps


@@ -102,8 +128,9 @@ for details.
 
   A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
 remaining elements of the list define the key bindings of the keymap.
 
   A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
 remaining elements of the list define the key bindings of the keymap.

-Use the function @code{keymapp} (see below) to test whether an object is
-a keymap.
+A symbol whose function definition is a keymap is also a keymap.  Use
+the function @code{keymapp} (see below) to test whether an object is a
+keymap.

 
   Several kinds of elements may appear in a keymap, after the symbol
 @code{keymap} that begins it:
 
   Several kinds of elements may appear in a keymap, after the symbol
 @code{keymap} that begins it:


@@ -120,24 +147,27 @@ This specifies a @dfn{default key binding}; any event not bound by other
 elements of the keymap is given @var{binding} as its binding.  Default
 bindings allow a keymap to bind all possible event types without having
 to enumerate all of them.  A keymap that has a default binding
 elements of the keymap is given @var{binding} as its binding.  Default
 bindings allow a keymap to bind all possible event types without having
 to enumerate all of them.  A keymap that has a default binding

-completely masks any lower-precedence keymap.
-
-@item @var{vector}
-If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ascii} characters, codes 0 through 127; vector element
-@var{n} is the binding for the character with code @var{n}.  This is a
-compact way to record lots of bindings.  A keymap with such a vector is
-called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
-keymaps}.
-
-When a keymap contains a vector, it always defines a binding for each
-@sc{ascii} character, even if the vector contains @code{nil} for that
-character.  Such a binding of @code{nil} overrides any default key
-binding in the keymap, for @sc{ascii} characters.  However, default
-bindings are still meaningful for events other than @sc{ascii}
-characters.  A binding of @code{nil} does @emph{not} override
-lower-precedence keymaps; thus, if the local map gives a binding of
-@code{nil}, Emacs uses the binding from the global map.
+completely masks any lower-precedence keymap, except for events
+explicitly bound to @code{nil} (see below).
+
+@item @var{char-table}
+If an element of a keymap is a char-table, it counts as holding
+bindings for all character events with no modifier bits
+(@pxref{modifier bits}): element @var{n} is the binding for the
+character with code @var{n}.  This is a compact way to record lots of
+bindings.  A keymap with such a char-table is called a @dfn{full
+keymap}.  Other keymaps are called @dfn{sparse keymaps}.
+
+When a keymap contains a char-table vector, it always defines a
+binding for each character without modifiers.  However, if the binding
+is @code{nil}, it doesn't constitute a definition.  @code{nil} takes
+precedence over a default binding or a binding in the parent keymap.
+So in a full keymap, default bindings are not meaningful for
+characters without modifiers.  They can still apply to characters with
+modifier bits and to non-character events.  A binding of @code{nil}
+does @emph{not} override lower-precedence keymaps; thus, if the local
+map gives a binding of @code{nil}, Emacs uses the binding from the
+global map.

 
 @item @var{string}
 @cindex keymap prompt string
 
 @item @var{string}
 @cindex keymap prompt string


@@ -145,17 +175,21 @@ lower-precedence keymaps; thus, if the local map gives a binding of
 @cindex prompt string of keymap
 Aside from bindings, a keymap can also have a string as an element.
 This is called the @dfn{overall prompt string} and makes it possible to
 @cindex prompt string of keymap
 Aside from bindings, a keymap can also have a string as an element.
 This is called the @dfn{overall prompt string} and makes it possible to

-use the keymap as a menu.  @xref{Menu Keymaps}.
+use the keymap as a menu.  @xref{Defining Menus}.

 @end table
 
 @cindex meta characters lookup
   Keymaps do not directly record bindings for the meta characters.
 @end table
 
 @cindex meta characters lookup
   Keymaps do not directly record bindings for the meta characters.

-Instead, meta characters are regarded for
-purposes of key lookup as sequences of two characters, the first of
-which is @key{ESC} (or whatever is currently the value of
-@code{meta-prefix-char}).  Thus, the key @kbd{M-a} is really represented
-as @kbd{@key{ESC} a}, and its global binding is found at the slot for
-@kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).
+Instead, meta characters are regarded for purposes of key lookup as
+sequences of two characters, the first of which is @key{ESC} (or
+whatever is currently the value of @code{meta-prefix-char}).  Thus, the
+key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
+global binding is found at the slot for @kbd{a} in @code{esc-map}
+(@pxref{Prefix Keys}).
+
+  This conversion applies only to characters, not to function keys or
+other input events; thus, @kbd{M-@key{end}} has nothing to do with
+@kbd{@key{ESC} @key{end}}.

 
   Here as an example is the local keymap for Lisp mode, a sparse
 keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
 
   Here as an example is the local keymap for Lisp mode, a sparse
 keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c


@@ -164,35 +198,41 @@ C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
 @example
 @group
 lisp-mode-map
 @example
 @group
 lisp-mode-map

-@result{} 
+@result{}

 @end group
 @group
 @end group
 @group

-(keymap 
- ;; @key{TAB}
- (9 . lisp-indent-line)                 
+(keymap
+ (3 keymap
+    ;; @kbd{C-c C-z}
+    (26 . run-lisp))

 @end group
 @group
 @end group
 @group

- ;; @key{DEL}
- (127 . backward-delete-char-untabify)  
+ (27 keymap
+     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
+     (24 . lisp-send-defun)
+     keymap
+     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
+     (17 . indent-sexp)))

 @end group
 @group
 @end group
 @group

- (3 keymap 
-    ;; @kbd{C-c C-l}
-    (12 . run-lisp))                    
+ ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
+ keymap
+ ;; @key{DEL}
+ (127 . backward-delete-char-untabify)

 @end group
 @group
 @end group
 @group

- (27 keymap 
+ (27 keymap

      ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
      ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}

-     (17 . indent-sexp)                 
-     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
-     (24 . lisp-send-defun)))           
+     (17 . indent-sexp))
+ (9 . lisp-indent-line))

 @end group
 @end example
 
 @defun keymapp object
 This function returns @code{t} if @var{object} is a keymap, @code{nil}
 otherwise.  More precisely, this function tests for a list whose
 @end group
 @end example
 
 @defun keymapp object
 This function returns @code{t} if @var{object} is a keymap, @code{nil}
 otherwise.  More precisely, this function tests for a list whose

-@sc{car} is @code{keymap}.
+@sc{car} is @code{keymap}, or for a symbol whose function definition
+satisfies @code{keymapp}.

 
 @example
 @group
 
 @example
 @group


@@ -200,6 +240,11 @@ otherwise.  More precisely, this function tests for a list whose
     @result{} t
 @end group
 @group
     @result{} t
 @end group
 @group

+(fset 'foo '(keymap))
+(keymapp 'foo)
+    @result{} t
+@end group
+@group

 (keymapp (current-global-map))
     @result{} t
 @end group
 (keymapp (current-global-map))
     @result{} t
 @end group


@@ -214,27 +259,29 @@ otherwise.  More precisely, this function tests for a list whose
 
 @c ??? This should come after make-sparse-keymap
 @defun make-keymap &optional prompt
 
 @c ??? This should come after make-sparse-keymap
 @defun make-keymap &optional prompt

-This function creates and returns a new full keymap (i.e., one
-containing a vector of length 128 for defining all the @sc{ascii}
-characters).  The new keymap initially binds all @sc{ascii} characters
-to @code{nil}, and does not bind any other kind of event.
+This function creates and returns a new full keymap.  That keymap
+contains a char-table (@pxref{Char-Tables}) with slots for all
+characters without modifiers.  The new keymap initially binds all
+these characters to @code{nil}, and does not bind any other kind of
+event.

 
 @example
 @group
 (make-keymap)
 
 @example
 @group
 (make-keymap)

-    @result{} (keymap [nil nil nil @dots{} nil nil])
+    @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])

 @end group
 @end example
 
 If you specify @var{prompt}, that becomes the overall prompt string for
 @end group
 @end example
 
 If you specify @var{prompt}, that becomes the overall prompt string for

-the keymap.  The prompt string is useful for menu keymaps (@pxref{Menu
-Keymaps}).
+the keymap.  The prompt string should be provided for menu keymaps
+(@pxref{Defining Menus}).

 @end defun
 
 @defun make-sparse-keymap &optional prompt
 This function creates and returns a new sparse keymap with no entries.
 @end defun
 
 @defun make-sparse-keymap &optional prompt
 This function creates and returns a new sparse keymap with no entries.

-The new keymap does not bind any events.  The argument @var{prompt}
-specifies a prompt string, as in @code{make-keymap}.
+The new keymap does not contain a char-table, unlike @code{make-keymap},
+and does not bind any events.  The argument @var{prompt} specifies a
+prompt string, as in @code{make-keymap}.

 
 @example
 @group
 
 @example
 @group


@@ -259,7 +306,7 @@ definition is a keymap; the same symbol appears in the new copy.
 @end group
 @group
      ;; @r{(This implements meta characters.)}
 @end group
 @group
      ;; @r{(This implements meta characters.)}

-     (27 keymap         
+     (27 keymap

          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))
          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))


@@ -319,7 +366,7 @@ new parent keymaps that reflect what @var{parent} specifies for those
 prefix keys.
 @end defun
 
 prefix keys.
 @end defun
 

-Here is an example showing how to make a keymap that inherits
+   Here is an example showing how to make a keymap that inherits

 from @code{text-mode-map}:
 
 @example
 from @code{text-mode-map}:
 
 @example


@@ -328,6 +375,12 @@ from @code{text-mode-map}:
   map)
 @end example
 
   map)
 @end example
 

+  A non-sparse keymap can have a parent too, but this is not very
+useful.  A non-sparse keymap always specifies something as the binding
+for every numeric character code without modifier bits, even if it is
+@code{nil}, so these character's bindings are never inherited from
+the parent keymap.
+

 @node Prefix Keys
 @section Prefix Keys
 @cindex prefix key
 @node Prefix Keys
 @section Prefix Keys
 @cindex prefix key


@@ -403,16 +456,16 @@ key.
 key.
 
 @item
 key.
 
 @item

-@cindex @kbd{M-g}
+@cindex @kbd{M-o}

 @vindex facemenu-keymap
 @vindex facemenu-keymap

-@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-o}

 prefix key.
 
 @c Emacs 19 feature
 @item
 prefix key.
 
 @c Emacs 19 feature
 @item

-The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
-@key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps that have no
-special names.
+The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
+@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps
+that have no special names.

 @end itemize
 
   The keymap binding of a prefix key is used for looking up the event
 @end itemize
 
   The keymap binding of a prefix key is used for looking up the event


@@ -463,8 +516,9 @@ active keymap.
 
 @defun define-prefix-command symbol &optional mapvar prompt
 @cindex prefix command
 
 @defun define-prefix-command symbol &optional mapvar prompt
 @cindex prefix command

+@anchor{Definition of define-prefix-command}

 This function prepares @var{symbol} for use as a prefix key's binding:
 This function prepares @var{symbol} for use as a prefix key's binding:

-it creates a full keymap and stores it as @var{symbol}'s function
+it creates a sparse keymap and stores it as @var{symbol}'s function

 definition.  Subsequently binding a key sequence to @var{symbol} will
 make that key sequence into a prefix key.  The return value is @code{symbol}.
 
 definition.  Subsequently binding a key sequence to @var{symbol} will
 make that key sequence into a prefix key.  The return value is @code{symbol}.
 


@@ -473,8 +527,8 @@ its value.  But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
 as a variable instead.
 
 If @var{prompt} is non-@code{nil}, that becomes the overall prompt
 as a variable instead.
 
 If @var{prompt} is non-@code{nil}, that becomes the overall prompt

-string for the keymap.  The prompt string is useful for menu keymaps
-(@pxref{Menu Keymaps}).
+string for the keymap.  The prompt string should be given for menu keymaps
+(@pxref{Defining Menus}).

 @end defun
 
 @node Active Keymaps
 @end defun
 
 @node Active Keymaps


@@ -483,40 +537,46 @@ string for the keymap.  The prompt string is useful for menu keymaps
 @cindex global keymap
 @cindex local keymap
 
 @cindex global keymap
 @cindex local keymap
 

-  Emacs normally contains many keymaps; at any given time, just a few of
-them are @dfn{active} in that they participate in the interpretation
-of user input.  These are the global keymap, the current buffer's
-local keymap, and the keymaps of any enabled minor modes.
+  Emacs normally contains many keymaps; at any given time, just a few
+of them are @dfn{active} in that they participate in the
+interpretation of user input.  All the active keymaps are used
+together to determine what command to execute when a key is entered.
+Emacs searches these keymaps one by one, in a standard order, until it
+finds a binding in one of the keymaps.  (Searching a single keymap for a
+binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
+
+  Normally the active keymaps are the @code{keymap} property keymap,
+the keymaps of any enabled minor modes, the current buffer's local
+keymap, and the global keymap, in that order.  Therefore, Emacs
+searches for each input key sequence in all these keymaps.

 
   The @dfn{global keymap} holds the bindings of keys that are defined
 regardless of the current buffer, such as @kbd{C-f}.  The variable
 @code{global-map} holds this keymap, which is always active.
 
 
   The @dfn{global keymap} holds the bindings of keys that are defined
 regardless of the current buffer, such as @kbd{C-f}.  The variable
 @code{global-map} holds this keymap, which is always active.
 

-  Each buffer may have another keymap, its @dfn{local keymap}, which may
-contain new or overriding definitions for keys.  The current buffer's
-local keymap is always active except when @code{overriding-local-map}
-overrides it.  Text properties can specify an alternative local map for
-certain parts of the buffer; see @ref{Special Properties}.
+  Each buffer may have another keymap, its @dfn{local keymap}, which
+may contain new or overriding definitions for keys.  The current
+buffer's local keymap is always active except when
+@code{overriding-local-map} overrides it.  The @code{local-map} text
+or overlay property can specify an alternative local keymap for certain
+parts of the buffer; see @ref{Special Properties}.

 
   Each minor mode can have a keymap; if it does, the keymap is active
 
   Each minor mode can have a keymap; if it does, the keymap is active

-when the minor mode is enabled.
-
-  The variable @code{overriding-local-map}, if non-@code{nil}, specifies
-another local keymap that overrides the buffer's local map and all the 
-minor mode keymaps.
-
-  All the active keymaps are used together to determine what command to
-execute when a key is entered.  Emacs searches these maps one by one, in
-order of decreasing precedence, until it finds a binding in one of the
-maps.  The procedure for searching a single keymap is called @dfn{key
-lookup}; see @ref{Key Lookup}.
-
-  Normally, Emacs first searches for the key in the minor mode maps, in
-the order specified by @code{minor-mode-map-alist}; if they do not
-supply a binding for the key, Emacs searches the local map; if that too
-has no binding, Emacs then searches the global map.  However, if
-@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
-first, before the global map.
+when the minor mode is enabled.  Modes for emulation can specify
+additional active keymaps through the variable
+@code{emulation-mode-map-alists}.
+
+  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.
+
+  However, there are also special ways for program can 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.

 
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the
 
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the


@@ -525,7 +585,7 @@ change to the local keymap of a buffer (using @code{local-set-key}, for
 example) is seen also in the other buffers that share that keymap.
 
   The local keymaps that are used for Lisp mode and some other major
 example) is seen also in the other buffers that share that keymap.
 
   The local keymaps that are used for Lisp mode and some other major

-modes exist even if they have not yet been used.  These local maps are
+modes exist even if they have not yet been used.  These local keymaps are

 the values of variables such as @code{lisp-mode-map}.  For most major
 modes, which are less frequently used, the local keymap is constructed
 only when the mode is used for the first time in a session.
 the values of variables such as @code{lisp-mode-map}.  For most major
 modes, which are less frequently used, the local keymap is constructed
 only when the mode is used for the first time in a session.


@@ -544,7 +604,7 @@ keyboard input to commands.  The global keymap is normally this keymap.
 The default global keymap is a full keymap that binds
 @code{self-insert-command} to all of the printing characters.
 
 The default global keymap is a full keymap that binds
 @code{self-insert-command} to all of the printing characters.
 

-It is normal practice to change the bindings in the global map, but you
+It is normal practice to change the bindings in the global keymap, but you

 should not assign this variable any value other than the keymap it starts
 out with.
 @end defvar
 should not assign this variable any value other than the keymap it starts
 out with.
 @end defvar


@@ -557,7 +617,7 @@ other.
 @example
 @group
 (current-global-map)
 @example
 @group
 (current-global-map)

-@result{} (keymap [set-mark-command beginning-of-line @dots{} 
+@result{} (keymap [set-mark-command beginning-of-line @dots{}

             delete-backward-char])
 @end group
 @end example
             delete-backward-char])
 @end group
 @end example


@@ -567,20 +627,20 @@ other.
 This function returns the current buffer's local keymap, or @code{nil}
 if it has none.  In the following example, the keymap for the
 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
 This function returns the current buffer's local keymap, or @code{nil}
 if it has none.  In the following example, the keymap for the
 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap

-in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
+in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse

 keymap.
 
 @example
 @group
 (current-local-map)
 keymap.
 
 @example
 @group
 (current-local-map)

-@result{} (keymap 
-    (10 . eval-print-last-sexp) 
-    (9 . lisp-indent-line) 
-    (127 . backward-delete-char-untabify) 
+@result{} (keymap
+    (10 . eval-print-last-sexp)
+    (9 . lisp-indent-line)
+    (127 . backward-delete-char-untabify)

 @end group
 @group
 @end group
 @group

-    (27 keymap 
-        (24 . eval-defun) 
+    (27 keymap
+        (24 . eval-defun)

         (17 . indent-sexp)))
 @end group
 @end example
         (17 . indent-sexp)))
 @end group
 @end example


@@ -624,8 +684,8 @@ structure as elements of @code{minor-mode-alist}.  The map must be the
 not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
 function definition is a keymap.
 
 not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
 function definition is a keymap.
 

-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}.  But you should design
+When more than one minor mode keymap is active, the earlier one in
+@code{minor-mode-map-alist} takes priority.  But you should design

 minor modes so that they don't interfere with each other.  If you do
 this properly, the order will not matter.
 
 minor modes so that they don't interfere with each other.  If you do
 this properly, the order will not matter.
 


@@ -651,15 +711,15 @@ all buffers.
 
 @defvar overriding-local-map
 If non-@code{nil}, this variable holds a keymap to use instead of the
 
 @defvar overriding-local-map
 If non-@code{nil}, this variable holds a keymap to use instead of the

-buffer's local keymap and instead of all the minor mode keymaps.  This
-keymap, if any, overrides all other maps that would have been active,
-except for the current global map.
+buffer's local keymap, any text property or overlay keymaps, and any
+minor mode keymaps.  This keymap, if specified, overrides all other
+maps that would have been active, except for the current global map.

 @end defvar
 
 @defvar overriding-terminal-local-map
 If non-@code{nil}, this variable holds a keymap to use instead of
 @end defvar
 
 @defvar overriding-terminal-local-map
 If non-@code{nil}, this variable holds a keymap to use instead of

-@code{overriding-local-map}, the buffer's local keymap and all the minor
-mode keymaps.
+@code{overriding-local-map}, the buffer's local keymap, text property
+or overlay keymaps, and all the minor mode keymaps.

 
 This variable is always local to the current terminal and cannot be
 buffer-local.  @xref{Multiple Displays}.  It is used to implement
 
 This variable is always local to the current terminal and cannot be
 buffer-local.  @xref{Multiple Displays}.  It is used to implement


@@ -687,6 +747,16 @@ binding in this keymap, then it is special, and the binding for the
 event is run directly by @code{read-event}.  @xref{Special Events}.
 @end defvar
 
 event is run directly by @code{read-event}.  @xref{Special Events}.
 @end defvar
 

+@defvar emulation-mode-map-alists
+This variable holds a list of keymap alists to use for emulations
+modes.  It is intended for modes or packages using multiple minor-mode
+keymaps.  Each element is a keymap alist which has the same format and
+meaning as @code{minor-mode-map-alist}, or a symbol with a variable
+binding which is such an alist.  The ``active'' keymaps in each alist
+are used before @code{minor-mode-map-alist} and
+@code{minor-mode-overriding-map-alist}.
+@end defvar
+

 @node Key Lookup
 @section Key Lookup
 @cindex key lookup
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup


@@ -698,8 +768,8 @@ part of key lookup.
 
   Key lookup uses just the event type of each event in the key sequence;
 the rest of the event is ignored.  In fact, a key sequence used for key
 
   Key lookup uses just the event type of each event in the key sequence;
 the rest of the event is ignored.  In fact, a key sequence used for key

-lookup may designate mouse events with just their types (symbols)
-instead of with entire mouse events (lists).  @xref{Input Events}.  Such
+lookup may designate a mouse event with just its types (a symbol)
+instead of the entire event (a list).  @xref{Input Events}.  Such

 a ``key-sequence'' is insufficient for @code{command-execute} to run,
 but it is sufficient for looking up or rebinding a key.
 
 a ``key-sequence'' is insufficient for @code{command-execute} to run,
 but it is sufficient for looking up or rebinding a key.
 


@@ -844,6 +914,10 @@ the other functions described in this chapter that look up keys use
     @result{} find-file
 @end group
 @group
     @result{} find-file
 @end group
 @group

+(lookup-key (current-global-map) (kbd "C-x C-f"))
+    @result{} find-file
+@end group
+@group

 (lookup-key (current-global-map) "\C-x\C-f12345")
     @result{} 2
 @end group
 (lookup-key (current-global-map) "\C-x\C-f12345")
     @result{} 2
 @end group


@@ -863,9 +937,9 @@ the specific sequence @var{key}, ignoring default bindings except when
 you explicitly ask about them.  (To do this, supply @code{t} as an
 element of @var{key}; see @ref{Format of Keymaps}.)
 
 you explicitly ask about them.  (To do this, supply @code{t} as an
 element of @var{key}; see @ref{Format of Keymaps}.)
 

-If @var{key} contains a meta character, that character is implicitly
-replaced by a two-character sequence: the value of
-@code{meta-prefix-char}, followed by the corresponding non-meta
+If @var{key} contains a meta character (not a function key), that
+character is implicitly replaced by a two-character sequence: the value
+of @code{meta-prefix-char}, followed by the corresponding non-meta

 character.  Thus, the first example below is handled by conversion into
 the second example.
 
 character.  Thus, the first example below is handled by conversion into
 the second example.
 


@@ -891,7 +965,7 @@ Used in keymaps to undefine keys.  It calls @code{ding}, but does
 not cause an error.
 @end deffn
 
 not cause an error.
 @end deffn
 

-@defun key-binding key &optional accept-defaults
+@defun key-binding key &optional accept-defaults no-remap

 This function returns the binding for @var{key} in the current
 keymaps, trying all the active keymaps.  The result is @code{nil} if
 @var{key} is undefined in the keymaps.
 This function returns the binding for @var{key} in the current
 keymaps, trying all the active keymaps.  The result is @code{nil} if
 @var{key} is undefined in the keymaps.


@@ -900,6 +974,12 @@ keymaps, trying all the active keymaps.  The result is @code{nil} if
 The argument @var{accept-defaults} controls checking for default
 bindings, as in @code{lookup-key} (above).
 
 The argument @var{accept-defaults} controls checking for default
 bindings, as in @code{lookup-key} (above).
 

+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed.  However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+

 An error is signaled if @var{key} is not a string or a vector.
 
 @example
 An error is signaled if @var{key} is not a string or a vector.
 
 @example


@@ -910,6 +990,14 @@ An error is signaled if @var{key} is not a string or a vector.
 @end example
 @end defun
 
 @end example
 @end defun
 

+@defun current-active-maps &optional olp
+This returns the list of keymaps that would be used by the command
+loop in the current circumstances to look up a key sequence.  Normally
+it ignores @code{overriding-local-map} and
+@code{overriding-terminal-local-map}, but if @var{olp} is
+non-@code{nil} then it pays attention to them.
+@end defun
+

 @defun local-key-binding key &optional accept-defaults
 This function returns the binding for @var{key} in the current
 local keymap, or @code{nil} if it is undefined there.
 @defun local-key-binding key &optional accept-defaults
 This function returns the binding for @var{key} in the current
 local keymap, or @code{nil} if it is undefined there.


@@ -952,14 +1040,15 @@ This variable is the meta-prefix character code.  It is used when
 translating a meta character to a two-character sequence so it can be
 looked up in a keymap.  For useful results, the value should be a prefix
 event (@pxref{Prefix Keys}).  The default value is 27, which is the
 translating a meta character to a two-character sequence so it can be
 looked up in a keymap.  For useful results, the value should be a prefix
 event (@pxref{Prefix Keys}).  The default value is 27, which is the

-@sc{ascii} code for @key{ESC}.
+@acronym{ASCII} code for @key{ESC}.

 
 

-As long as the value of @code{meta-prefix-char} remains 27, key
-lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
-defined as the @code{backward-word} command.  However, if you set
+As long as the value of @code{meta-prefix-char} remains 27, key lookup
+translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
+as the @code{backward-word} command.  However, if you were to set

 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the

-@code{switch-to-buffer} command.  Here is an illustration:
+@code{switch-to-buffer} command.  (Don't actually do this!)  Here is an
+illustration of what would happen:

 
 @smallexample
 @group
 
 @smallexample
 @group


@@ -976,7 +1065,7 @@ meta-prefix-char                    ; @r{The default value.}
 @end group
 @group
 (setq meta-prefix-char 24)
 @end group
 @group
 (setq meta-prefix-char 24)

-     @result{} 24      
+     @result{} 24

 @end group
 @group
 (key-binding "\M-b")
 @end group
 @group
 (key-binding "\M-b")


@@ -987,6 +1076,10 @@ meta-prefix-char                    ; @r{The default value.}
      @result{} 27                          ; @r{Restore the default value!}
 @end group
 @end smallexample
      @result{} 27                          ; @r{Restore the default value!}
 @end group
 @end smallexample

+
+This translation of one event into two happens only for characters, not
+for other kinds of input events.  Thus, @kbd{M-@key{F1}}, a function
+key, is not converted into @kbd{@key{ESC} @key{F1}}.

 @end defvar
 
 @node Changing Key Bindings
 @end defvar
 
 @node Changing Key Bindings


@@ -1025,10 +1118,11 @@ key name).  For example, @code{(control ?a)} is equivalent to
 @code{C-H-left}.  One advantage of such lists is that the precise
 numeric codes for the modifier bits don't appear in compiled files.
 
 @code{C-H-left}.  One advantage of such lists is that the precise
 numeric codes for the modifier bits don't appear in compiled files.
 

-  For the functions below, an error is signaled if @var{keymap} is not a
-keymap or if @var{key} is not a string or vector representing a key
+  For the functions below, an error is signaled if @var{keymap} is not
+a keymap or if @var{key} is not a string or vector representing a key

 sequence.  You can use event types (symbols) as shorthand for events
 sequence.  You can use event types (symbols) as shorthand for events

-that are lists.
+that are lists.  The @code{kbd} macro (@pxref{Keymap Terminology}) is
+a convenient way to specify the key sequence.

 
 @defun define-key keymap key binding
 This function sets the binding for @var{key} in @var{keymap}.  (If
 
 @defun define-key keymap key binding
 This function sets the binding for @var{key} in @var{keymap}.  (If


@@ -1038,6 +1132,10 @@ in another keymap reached from @var{keymap}.)  The argument
 meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
 The value returned by @code{define-key} is @var{binding}.
 
 meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
 The value returned by @code{define-key} is @var{binding}.
 

+If @var{key} is @code{[t]}, this sets the default binding in
+@var{keymap}.  When an event has no binding of its own, the Emacs
+command loop uses the keymap's default binding, if there is one.
+

 @cindex invalid prefix key error
 @cindex key sequence error
 Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
 @cindex invalid prefix key error
 @cindex key sequence error
 Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)


@@ -1047,8 +1145,8 @@ key so that the rest of @var{key} can be defined as specified.
 
 If there was previously no binding for @var{key} in @var{keymap}, the
 new binding is added at the beginning of @var{keymap}.  The order of
 
 If there was previously no binding for @var{key} in @var{keymap}, the
 new binding is added at the beginning of @var{keymap}.  The order of

-bindings in a keymap makes no difference in most cases, but it does
-matter for menu keymaps (@pxref{Menu Keymaps}).
+bindings in a keymap makes no difference for keyboard input, but it
+does matter for menu keymaps (@pxref{Menu Keymaps}).

 @end defun
 
   Here is an example that creates a sparse keymap and makes a number of
 @end defun
 
   Here is an example that creates a sparse keymap and makes a number of


@@ -1070,12 +1168,12 @@ map
 
 @group
 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
 
 @group
 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}

-(define-key map "\C-xf" 'forward-word)
+(define-key map (kbd "C-x f") 'forward-word)

     @result{} forward-word
 @end group
 @group
 map
     @result{} forward-word
 @end group
 @group
 map

-@result{} (keymap 
+@result{} (keymap

     (24 keymap                ; @kbd{C-x}
         (102 . forward-word)) ;      @kbd{f}
     (6 . forward-char))       ; @kbd{C-f}
     (24 keymap                ; @kbd{C-x}
         (102 . forward-word)) ;      @kbd{f}
     (6 . forward-char))       ; @kbd{C-f}


@@ -1083,21 +1181,21 @@ map
 
 @group
 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
 
 @group
 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}

-(define-key map "\C-p" ctl-x-map)
+(define-key map (kbd "C-p") ctl-x-map)

 ;; @code{ctl-x-map}
 ;; @code{ctl-x-map}

-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] 
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]

 @end group
 
 @group
 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
 @end group
 
 @group
 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}

-(define-key map "\C-p\C-f" 'foo)
+(define-key map (kbd "C-p C-f") 'foo)

 @result{} 'foo
 @end group
 @group
 map
 @result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
     (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
 @result{} 'foo
 @end group
 @group
 map
 @result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
     (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])

-    (24 keymap 
+    (24 keymap

         (102 . forward-word))
     (6 . forward-char))
 @end group
         (102 . forward-word))
     (6 . forward-char))
 @end group


@@ -1109,6 +1207,12 @@ changing an entry in @code{ctl-x-map}, and this has the effect of
 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
 default global map.
 
 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
 default global map.
 

+  The function @code{substitute-key-definition} scans a keymap for
+keys that have a certain binding and rebinds them with a different
+binding.  Another feature you can use for similar effects, but which
+is often cleaner, is to add a binding that remaps a command
+(@pxref{Remapping Commands}).
+

 @defun substitute-key-definition olddef newdef keymap &optional oldmap
 @cindex replace bindings
 This function replaces @var{olddef} with @var{newdef} for any keys in
 @defun substitute-key-definition olddef newdef keymap &optional oldmap
 @cindex replace bindings
 This function replaces @var{olddef} with @var{newdef} for any keys in


@@ -1121,15 +1225,16 @@ standard bindings:
 
 @smallexample
 @group
 
 @smallexample
 @group

-(substitute-key-definition 
+(substitute-key-definition

  'find-file 'find-file-read-only (current-global-map))
 @end group
 @end smallexample
 
 @c Emacs 19 feature
  'find-file 'find-file-read-only (current-global-map))
 @end group
 @end smallexample
 
 @c Emacs 19 feature

-If @var{oldmap} is non-@code{nil}, then its bindings determine which
-keys to rebind.  The rebindings still happen in @var{keymap}, not in
-@var{oldmap}.  Thus, you can change one map under the control of the
+If @var{oldmap} is non-@code{nil}, that changes the behavior of
+@code{substitute-key-definition}: the bindings in @var{oldmap} determine
+which keys to rebind.  The rebindings still happen in @var{keymap}, not
+in @var{oldmap}.  Thus, you can change one map under the control of the

 bindings in another.  For example,
 
 @smallexample
 bindings in another.  For example,
 
 @smallexample


@@ -1142,20 +1247,13 @@ bindings in another.  For example,
 puts the special deletion command in @code{my-map} for whichever keys
 are globally bound to the standard deletion command.
 
 puts the special deletion command in @code{my-map} for whichever keys
 are globally bound to the standard deletion command.
 

-@ignore
-@c Emacs 18 only
-Prefix keymaps that appear within @var{keymap} are not checked
-recursively for keys bound to @var{olddef}; they are not changed at all.
-Perhaps it would be better to check nested keymaps recursively.
-@end ignore
-

 Here is an example showing a keymap before and after substitution:
 
 @smallexample
 @group
 Here is an example showing a keymap before and after substitution:
 
 @smallexample
 @group

-(setq map '(keymap 
-            (?1 . olddef-1) 
-            (?2 . olddef-2) 
+(setq map '(keymap
+            (?1 . olddef-1)
+            (?2 . olddef-2)

             (?3 . olddef-1)))
 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
 @end group
             (?3 . olddef-1)))
 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
 @end group


@@ -1174,17 +1272,18 @@ map
 @defun suppress-keymap keymap &optional nodigits
 @cindex @code{self-insert-command} override
 This function changes the contents of the full keymap @var{keymap} by
 @defun suppress-keymap keymap &optional nodigits
 @cindex @code{self-insert-command} override
 This function changes the contents of the full keymap @var{keymap} by

-making all the printing characters undefined.  More precisely, it binds
-them to the command @code{undefined}.  This makes ordinary insertion of
-text impossible.  @code{suppress-keymap} returns @code{nil}.
+remapping @code{self-insert-command} to the command @code{undefined}
+(@pxref{Remapping Commands}).  This has the effect of undefining all
+printing characters, thus making ordinary insertion of text impossible.
+@code{suppress-keymap} returns @code{nil}.

 
 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
 digits to run @code{digit-argument}, and @kbd{-} to run
 @code{negative-argument}.  Otherwise it makes them undefined like the
 rest of the printing characters.
 
 
 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
 digits to run @code{digit-argument}, and @kbd{-} to run
 @code{negative-argument}.  Otherwise it makes them undefined like the
 rest of the printing characters.
 

-@cindex yank suppression 
-@cindex @code{quoted-insert} suppression 
+@cindex yank suppression
+@cindex @code{quoted-insert} suppression

 The @code{suppress-keymap} function does not make it impossible to
 modify a buffer, as it does not suppress commands such as @code{yank}
 and @code{quoted-insert}.  To prevent any modification of a buffer, make
 The @code{suppress-keymap} function does not make it impossible to
 modify a buffer, as it does not suppress commands such as @code{yank}
 and @code{quoted-insert}.  To prevent any modification of a buffer, make


@@ -1217,6 +1316,57 @@ Dired mode is set up:
 @end smallexample
 @end defun
 
 @end smallexample
 @end defun
 

+@node Remapping Commands
+@section Remapping Commands
+@cindex remapping commands
+
+  A special kind of key binding, using a special ``key sequence''
+which includes a command name, has the effect of @dfn{remapping} that
+command into another.  Here's how it works.  You make a key binding
+for a key sequence that starts with the dummy event @code{remap},
+followed by the command name you want to remap.  Specify the remapped
+definition as the definition in this binding.  The remapped definition
+is usually a command name, but it can be any valid definition for
+a key binding.
+
+  Here's an example.  Suppose that My mode uses special commands
+@code{my-kill-line} and @code{my-kill-word}, which should be invoked
+instead of @code{kill-line} and @code{kill-word}.  It can establish
+this by making these two command-remapping bindings in its keymap:
+
+@example
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap kill-word] 'my-kill-word)
+@end example
+
+Whenever @code{my-mode-map} is an active keymap, if the user types
+@kbd{C-k}, Emacs will find the standard global binding of
+@code{kill-line} (assuming nobody has changed it).  But
+@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
+so instead of running @code{kill-line}, Emacs runs
+@code{my-kill-line}.
+
+Remapping only works through a single level.  In other words,
+
+@example
+(define-key my-mode-map [remap kill-line] 'my-kill-line)
+(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
+@end example
+
+@noindent
+does not have the effect of remapping @code{kill-line} into
+@code{my-other-kill-line}.  If an ordinary key binding specifies
+@code{kill-line}, this keymap will remap it to @code{my-kill-line};
+if an ordinary binding specifies @code{my-kill-line}, this keymap will
+remap it to @code{my-other-kill-line}.
+
+@defun command-remapping command
+This function returns the remapping for @var{command} (a symbol),
+given the current active keymaps.  If @var{command} is not remapped
+(which is the usual situation), or not a symbol, the function returns
+@code{nil}.
+@end defun
+

 @node Key Binding Commands
 @section Commands for Binding Keys
 
 @node Key Binding Commands
 @section Commands for Binding Keys
 


@@ -1227,7 +1377,7 @@ changing key bindings.  They work by calling @code{define-key}.
 (@pxref{Init File}) for simple customization.  For example,
 
 @smallexample
 (@pxref{Init File}) for simple customization.  For example,
 
 @smallexample

-(global-set-key "\C-x\C-\\" 'next-line)
+(global-set-key (kbd "C-x C-\\") 'next-line)

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent


@@ -1252,11 +1402,11 @@ redefines @kbd{C-x C-\} to move down a line.
 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent

-redefines the first (leftmost) mouse button, typed with the Meta key, to
+redefines the first (leftmost) mouse button, entered with the Meta key, to

 set point where you click.
 
 set point where you click.
 

-@cindex non-ASCII text in keybindings
-  Be careful when using non-@sc{ascii} text characters in Lisp
+@cindex non-@acronym{ASCII} text in keybindings
+  Be careful when using non-@acronym{ASCII} text characters in Lisp

 specifications of keys to bind.  If these are read as multibyte text, as
 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
 must type the keys as multibyte too.  For instance, if you use this:
 specifications of keys to bind.  If these are read as multibyte text, as
 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
 must type the keys as multibyte too.  For instance, if you use this:


@@ -1278,7 +1428,7 @@ actually bind the multibyte character with code 2294, not the unibyte
 Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
 binding, you need to enter the multibyte Latin-1 character as keyboard
 input.  One way to do this is by using an appropriate input method
 Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
 binding, you need to enter the multibyte Latin-1 character as keyboard
 input.  One way to do this is by using an appropriate input method

-(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
+(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).

 
   If you want to use a unibyte character in the key binding, you can
 construct the key sequence string using @code{multibyte-char-to-unibyte}
 
   If you want to use a unibyte character in the key binding, you can
 construct the key sequence string using @code{multibyte-char-to-unibyte}


@@ -1368,7 +1518,7 @@ association list with elements of the form @code{(@var{key} .@:
 @var{keymap} is @var{map}.
 
 The elements of the alist are ordered so that the @var{key} increases
 @var{keymap} is @var{map}.
 
 The elements of the alist are ordered so that the @var{key} increases

-in length.  The first element is always @code{("" .@: @var{keymap})},
+in length.  The first element is always @code{([] .@: @var{keymap})},

 because the specified keymap is accessible from itself with a prefix of
 no events.
 
 because the specified keymap is accessible from itself with a prefix of
 no events.
 


@@ -1386,7 +1536,7 @@ definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
 @smallexample
 @group
 (accessible-keymaps (current-local-map))
 @smallexample
 @group
 (accessible-keymaps (current-local-map))

-@result{}(("" keymap 
+@result{}(([] keymap

       (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
           (83 . center-paragraph)
           (115 . center-line))
       (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
           (83 . center-paragraph)
           (115 . center-line))


@@ -1394,8 +1544,8 @@ definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
 @end group
 
 @group
 @end group
 
 @group

-   ("^[" keymap 
-    (83 . center-paragraph) 
+   ("^[" keymap
+    (83 . center-paragraph)

     (115 . foo)))
 @end group
 @end smallexample
     (115 . foo)))
 @end group
 @end smallexample


@@ -1410,7 +1560,7 @@ of a window.
 @smallexample
 @group
 (accessible-keymaps (current-global-map))
 @smallexample
 @group
 (accessible-keymaps (current-global-map))

-@result{} (("" keymap [set-mark-command beginning-of-line @dots{} 
+@result{} (([] keymap [set-mark-command beginning-of-line @dots{}

                    delete-backward-char])
 @end group
 @group
                    delete-backward-char])
 @end group
 @group


@@ -1436,10 +1586,22 @@ of a window.
 These are not all the keymaps you would see in actuality.
 @end defun
 
 These are not all the keymaps you would see in actuality.
 @end defun
 

-@defun where-is-internal command &optional keymap firstonly noindirect
+@defun map-keymap function keymap
+The function @code{map-keymap} calls @var{function} once
+for each binding in @var{keymap}.  It passes two arguments,
+the event type and the value of the binding.  If @var{keymap}
+has a parent, the parent's bindings are included as well.
+This works recursively: if the parent has itself a parent, then the
+grandparent's bindings are also included and so on.
+
+This function is the cleanest way to examine all the bindings
+in a keymap.
+@end defun
+
+@defun where-is-internal command &optional keymap firstonly noindirect no-remap

 This function is a subroutine used by the @code{where-is} command
 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
 This function is a subroutine used by the @code{where-is} command
 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list

-of key sequences (of any length) that are bound to @var{command} in a
+of all key sequences (of any length) that are bound to @var{command} in a

 set of keymaps.
 
 The argument @var{command} can be any object; it is compared with all
 set of keymaps.
 
 The argument @var{command} can be any object; it is compared with all


@@ -1447,8 +1609,9 @@ keymap entries using @code{eq}.
 
 If @var{keymap} is @code{nil}, then the maps used are the current active
 keymaps, disregarding @code{overriding-local-map} (that is, pretending
 
 If @var{keymap} is @code{nil}, then the maps used are the current active
 keymaps, disregarding @code{overriding-local-map} (that is, pretending

-its value is @code{nil}).  If @var{keymap} is non-@code{nil}, then the
-maps searched are @var{keymap} and the global keymap.
+its value is @code{nil}).  If @var{keymap} is a keymap, then the
+maps searched are @var{keymap} and the global keymap.  If @var{keymap}
+is a list of keymaps, only those keymaps are searched.

 
 Usually it's best to use @code{overriding-local-map} as the expression
 for @var{keymap}.  Then @code{where-is-internal} searches precisely the
 
 Usually it's best to use @code{overriding-local-map} as the expression
 for @var{keymap}.  Then @code{where-is-internal} searches precisely the


@@ -1456,16 +1619,24 @@ keymaps that are active.  To search only the global map, pass
 @code{(keymap)} (an empty keymap) as @var{keymap}.
 
 If @var{firstonly} is @code{non-ascii}, then the value is a single
 @code{(keymap)} (an empty keymap) as @var{keymap}.
 
 If @var{firstonly} is @code{non-ascii}, then the value is a single

-string representing the first key sequence found, rather than a list of
+vector representing the first key sequence found, rather than a list of

 all possible key sequences.  If @var{firstonly} is @code{t}, then the
 value is the first key sequence, except that key sequences consisting
 all possible key sequences.  If @var{firstonly} is @code{t}, then the
 value is the first key sequence, except that key sequences consisting

-entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
-characters) are preferred to all other key sequences.
+entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
+characters) are preferred to all other key sequences and that the
+return value can never be a menu binding.

 
 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
 follow indirect keymap bindings.  This makes it possible to search for
 an indirect definition itself.
 
 
 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
 follow indirect keymap bindings.  This makes it possible to search for
 an indirect definition itself.
 

+When command remapping is in effect (@pxref{Remapping Commands}),
+@code{where-is-internal} figures out when a command will be run due to
+remapping and reports keys accordingly.  It also returns @code{nil} if
+@var{command} won't really be run because it has been remapped to some
+other command.  However, if @var{no-remap} is non-@code{nil}.
+@code{where-is-internal} ignores remappings.
+

 @smallexample
 @group
 (where-is-internal 'describe-function)
 @smallexample
 @group
 (where-is-internal 'describe-function)


@@ -1474,7 +1645,7 @@ an indirect definition itself.
 @end smallexample
 @end defun
 
 @end smallexample
 @end defun
 

-@deffn Command describe-bindings &optional prefix
+@deffn Command describe-bindings &optional prefix buffer-or-name

 This function creates a listing of all current key bindings, and
 displays it in a buffer named @samp{*Help*}.  The text is grouped by
 modes---minor modes first, then the major mode, then global bindings.
 This function creates a listing of all current key bindings, and
 displays it in a buffer named @samp{*Help*}.  The text is grouped by
 modes---minor modes first, then the major mode, then global bindings.


@@ -1485,15 +1656,19 @@ listing includes only keys that start with @var{prefix}.
 The listing describes meta characters as @key{ESC} followed by the
 corresponding non-meta character.
 
 The listing describes meta characters as @key{ESC} followed by the
 corresponding non-meta character.
 

-When several characters with consecutive @sc{ascii} codes have the
+When several characters with consecutive @acronym{ASCII} codes have the

 same definition, they are shown together, as
 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
 same definition, they are shown together, as
 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to

-know the @sc{ascii} codes to understand which characters this means.
+know the @acronym{ASCII} codes to understand which characters this means.

 For example, in the default global map, the characters @samp{@key{SPC}
 For example, in the default global map, the characters @samp{@key{SPC}

-..@: ~} are described by a single line.  @key{SPC} is @sc{ascii} 32,
-@kbd{~} is @sc{ascii} 126, and the characters between them include all
+..@: ~} are described by a single line.  @key{SPC} is @acronym{ASCII} 32,
+@kbd{~} is @acronym{ASCII} 126, and the characters between them include all

 the normal printing characters, (e.g., letters, digits, punctuation,
 etc.@:); all these characters are bound to @code{self-insert-command}.
 the normal printing characters, (e.g., letters, digits, punctuation,
 etc.@:); all these characters are bound to @code{self-insert-command}.

+
+If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
+buffer name.  Then @code{describe-bindings} lists that buffer's bindings,
+instead of the current buffer's.

 @end deffn
 
 @node Menu Keymaps
 @end deffn
 
 @node Menu Keymaps


@@ -1524,9 +1699,22 @@ work with the keyboard also.
 A keymap is suitable for menu use if it has an @dfn{overall prompt
 string}, which is a string that appears as an element of the keymap.
 (@xref{Format of Keymaps}.)  The string should describe the purpose of
 A keymap is suitable for menu use if it has an @dfn{overall prompt
 string}, which is a string that appears as an element of the keymap.
 (@xref{Format of Keymaps}.)  The string should describe the purpose of

-the menu.  The easiest way to construct a keymap with a prompt string is
-to specify the string as an argument when you call @code{make-keymap} or
-@code{make-sparse-keymap} (@pxref{Creating Keymaps}).
+the menu's commands.  Emacs displays the overall prompt string as the
+menu title in some cases, depending on the toolkit (if any) used for
+displaying menus.@footnote{It is required for menus which do not use a
+toolkit, e.g.@: under MS-DOS.}  Keyboard menus also display the overall
+prompt string.
+
+The easiest way to construct a keymap with a prompt string is to specify
+the string as an argument when you call @code{make-keymap},
+@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
+@code{define-prefix-command} (@pxref{Definition of define-prefix-command}).
+
+
+@defun keymap-prompt keymap
+This function returns the overall prompt string of @var{keymap},
+or @code{nil} if it has none.
+@end defun

 
 The order of items in the menu is the same as the order of bindings in
 the keymap.  Since @code{define-key} puts new bindings at the front, you
 
 The order of items in the menu is the same as the order of bindings in
 the keymap.  Since @code{define-key} puts new bindings at the front, you


@@ -1558,18 +1746,22 @@ looks like this:
 @noindent
 The @sc{car}, @var{item-string}, is the string to be displayed in the
 menu.  It should be short---preferably one to three words.  It should
 @noindent
 The @sc{car}, @var{item-string}, is the string to be displayed in the
 menu.  It should be short---preferably one to three words.  It should

-describe the action of the command it corresponds to.
+describe the action of the command it corresponds to.  Note that it is
+not generally possible to display non-@acronym{ASCII} text in menus.  It will
+work for keyboard menus and will work to a large extent when Emacs is
+built with the Gtk+ toolkit.@footnote{In this case, the text is first
+encoded using the @code{utf-8} coding system and then rendered by the
+toolkit as it sees fit.}

 
 You can also supply a second string, called the help string, as follows:
 
 @example
 
 You can also supply a second string, called the help string, as follows:
 
 @example

-(@var{item-string} @var{help-string} . @var{real-binding})
+(@var{item-string} @var{help} . @var{real-binding})

 @end example
 
 @end example
 

-Currently Emacs does not actually use @var{help-string}; it knows only
-how to ignore @var{help-string} in order to extract @var{real-binding}.
-In the future we may use @var{help-string} as extended documentation for
-the menu item, available on request.
+@var{help} specifies a ``help-echo'' string to display while the mouse
+is on that item in the same way as @code{help-echo} text properties
+(@pxref{Help display}).

 
 As far as @code{define-key} is concerned, @var{item-string} and
 @var{help-string} are part of the event's binding.  However,
 
 As far as @code{define-key} is concerned, @var{item-string} and
 @var{help-string} are part of the event's binding.  However,


@@ -1652,8 +1844,11 @@ does not appear, then the menu is displayed as if this item were
 not defined at all.
 
 @item :help @var{help}
 not defined at all.
 
 @item :help @var{help}

-The value of this property, @var{help}, is the extra help string (not
-currently used by Emacs).
+The value of this property, @var{help}, specifies a ``help-echo'' string
+to display while the mouse is on that item.  This is displayed in the
+same way as @code{help-echo} text properties (@pxref{Help display}).
+Note that this must be a constant string, unlike the @code{help-echo}
+property for text and overlays.

 
 @item :button (@var{type} . @var{selected})
 This property provides a way to define radio buttons and toggle buttons.
 
 @item :button (@var{type} . @var{selected})
 This property provides a way to define radio buttons and toggle buttons.


@@ -1721,7 +1916,7 @@ function should return the binding to use instead.
 @cindex menu separators
 
   A menu separator is a kind of menu item that doesn't display any
 @cindex menu separators
 
   A menu separator is a kind of menu item that doesn't display any

-text--instead, it divides the menu into subparts with a horizontal line.
+text---instead, it divides the menu into subparts with a horizontal line.

 A separator looks like this in the menu keymap:
 
 @example
 A separator looks like this in the menu keymap:
 
 @example


@@ -1735,8 +1930,8 @@ where @var{separator-type} is a string starting with two or more dashes.
 That specifies the default kind of separator.  (For compatibility,
 @code{""} and @code{-} also count as separators.)
 
 That specifies the default kind of separator.  (For compatibility,
 @code{""} and @code{-} also count as separators.)
 

-  Starting in Emacs 21, certain other values of @var{separator-type}
-specify a different style of separator.  Here is a table of them:
+  Certain other values of @var{separator-type} specify a different
+style of separator.  Here is a table of them:

 
 @table @code
 @item "--no-line"
 
 @table @code
 @item "--no-line"


@@ -1855,13 +2050,8 @@ with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
 special about @samp{@@} at the beginning of an item string is that the
 @samp{@@} doesn't appear in the menu item.
 
 special about @samp{@@} at the beginning of an item string is that the
 @samp{@@} doesn't appear in the menu item.
 

-  You can also produce multiple panes or submenus from separate keymaps.
-The full definition of a prefix key always comes from merging the
-definitions supplied by the various active keymaps (minor mode, local,
-and global).  When more than one of these keymaps is a menu, each of
-them makes a separate pane or panes (when Emacs does not use an
-X-toolkit) or a separate submenu (when using an X-toolkit).
-@xref{Active Keymaps}.
+  Multiple keymaps that define the same menu prefix key produce
+separate panes or separate submenus.

 
 @node Keyboard Menus
 @subsection Menus and the Keyboard
 
 @node Keyboard Menus
 @subsection Menus and the Keyboard


@@ -1870,12 +2060,13 @@ When a prefix key ending with a keyboard event (a character or function
 key) has a definition that is a menu keymap, the user can use the
 keyboard to choose a menu item.
 
 key) has a definition that is a menu keymap, the user can use the
 keyboard to choose a menu item.
 

-Emacs displays the menu alternatives (the item strings of the bindings)
-in the echo area.  If they don't all fit at once, the user can type
-@key{SPC} to see the next line of alternatives.  Successive uses of
-@key{SPC} eventually get to the end of the menu and then cycle around to
-the beginning.  (The variable @code{menu-prompt-more-char} specifies
-which character is used for this; @key{SPC} is the default.)
+Emacs displays the menu's overall prompt string followed by the
+alternatives (the item strings of the bindings) in the echo area.  If
+the bindings don't all fit at once, the user can type @key{SPC} to see
+the next line of alternatives.  Successive uses of @key{SPC} eventually
+get to the end of the menu and then cycle around to the beginning.  (The
+variable @code{menu-prompt-more-char} specifies which character is used
+for this; @key{SPC} is the default.)

 
 When the user has found the desired alternative from the menu, he or she
 should type the corresponding character---the one whose binding is that
 
 When the user has found the desired alternative from the menu, he or she
 should type the corresponding character---the one whose binding is that


@@ -1904,29 +2095,29 @@ for @key{SPC}.
 @cindex menu definition example
 
   Here is a complete example of defining a menu keymap.  It is the
 @cindex menu definition example
 
   Here is a complete example of defining a menu keymap.  It is the

-definition of the @samp{Print} submenu in the @samp{Tools} menu in the
-menu bar, and it uses the simple menu item format (@pxref{Simple Menu
-Items}).  First we create the keymap, and give it a name:
+definition of the @samp{Replace} submenu in the @samp{Edit} menu in
+the menu bar, and it uses the extended menu item format
+(@pxref{Extended Menu Items}).  First we create the keymap, and give
+it a name:

 
 

-@example
-(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
-@end example
+@smallexample
+(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
+@end smallexample

 
 @noindent
 Next we define the menu items:
 
 
 @noindent
 Next we define the menu items:
 

-@example
-(define-key menu-bar-print-menu [ps-print-region]
-  '("Postscript Print Region" . ps-print-region-with-faces))
-(define-key menu-bar-print-menu [ps-print-buffer]
-  '("Postscript Print Buffer" . ps-print-buffer-with-faces))
-(define-key menu-bar-print-menu [separator-ps-print]
-  '("--"))
-(define-key menu-bar-print-menu [print-region]
-  '("Print Region" . print-region))
-(define-key menu-bar-print-menu [print-buffer]
-  '("Print Buffer" . print-buffer))
-@end example
+@smallexample
+(define-key menu-bar-replace-menu [tags-repl-continue]
+  '(menu-item "Continue Replace" tags-loop-continue
+             :help "Continue last tags replace operation"))
+(define-key menu-bar-replace-menu [tags-repl]
+  '(menu-item "Replace in tagged files" tags-query-replace
+             :help "Interactively replace a regexp in all tagged files"))
+(define-key menu-bar-replace-menu [separator-replace-tags]
+  '(menu-item "--"))
+;; @r{@dots{}}
+@end smallexample

 
 @noindent
 Note the symbols which the bindings are ``made for''; these appear
 
 @noindent
 Note the symbols which the bindings are ``made for''; these appear


@@ -1938,60 +2129,37 @@ functioning of the menu itself, but they are ``echoed'' in the echo area
 when the user selects from the menu, and they appear in the output of
 @code{where-is} and @code{apropos}.
 
 when the user selects from the menu, and they appear in the output of
 @code{where-is} and @code{apropos}.
 

+  The menu in this example is intended for use with the mouse.  If a
+menu is intended for use with the keyboard, that is, if it is bound to
+a key sequence ending with a keyboard event, then the menu items
+should be bound to characters or ``real'' function keys, that can be
+typed with the keyboard.
+

   The binding whose definition is @code{("--")} is a separator line.
 Like a real menu item, the separator has a key symbol, in this case
   The binding whose definition is @code{("--")} is a separator line.
 Like a real menu item, the separator has a key symbol, in this case

-@code{separator-ps-print}.  If one menu has two separators, they must
-have two different key symbols.
-
-  Here is code to define enable conditions for two of the commands in
-the menu:
-
-@example
-(put 'print-region 'menu-enable 'mark-active)
-(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
-@end example
+@code{separator-replace-tags}.  If one menu has two separators, they
+must have two different key symbols.

 
   Here is how we make this menu appear as an item in the parent menu:
 
 @example
 
   Here is how we make this menu appear as an item in the parent menu:
 
 @example

-(define-key menu-bar-tools-menu [print]
-  (cons "Print" menu-bar-print-menu))
+(define-key menu-bar-edit-menu [replace]
+  (list 'menu-item "Replace" menu-bar-replace-menu))

 @end example
 
 @noindent
 Note that this incorporates the submenu keymap, which is the value of
 @end example
 
 @noindent
 Note that this incorporates the submenu keymap, which is the value of

-the variable @code{menu-bar-print-menu}, rather than the symbol
-@code{menu-bar-print-menu} itself.  Using that symbol in the parent menu
-item would be meaningless because @code{menu-bar-print-menu} is not a
-command.
+the variable @code{menu-bar-replace-menu}, rather than the symbol
+@code{menu-bar-replace-menu} itself.  Using that symbol in the parent
+menu item would be meaningless because @code{menu-bar-replace-menu} is
+not a command.

 
 

-  If you wanted to attach the same print menu to a mouse click, you
+  If you wanted to attach the same replace menu to a mouse click, you

 can do it this way:
 
 @example
 (define-key global-map [C-S-down-mouse-1]
 can do it this way:
 
 @example
 (define-key global-map [C-S-down-mouse-1]

-   menu-bar-print-menu)
-@end example
-
-  We could equally well use an extended menu item (@pxref{Extended Menu
-Items}) for @code{print-region}, like this:
-
-@example
-(define-key menu-bar-print-menu [print-region]
-  '(menu-item "Print Region" print-region
-              :enable (mark-active)))
-@end example
-
-@noindent
-With the extended menu item, the enable condition is specified
-inside the menu item itself.  If we wanted to make this
-item disappear from the menu entirely when the mark is inactive,
-we could do it this way:
-
-@example
-(define-key menu-bar-print-menu [print-region]
-  '(menu-item "Print Region" print-region
-              :visible (mark-active)))
+   menu-bar-replace-menu)

 @end example
 
 @node Menu Bar
 @end example
 
 @node Menu Bar


@@ -2001,7 +2169,7 @@ we could do it this way:
   Most window systems allow each frame to have a @dfn{menu bar}---a
 permanently displayed menu stretching horizontally across the top of the
 frame.  The items of the menu bar are the subcommands of the fake
   Most window systems allow each frame to have a @dfn{menu bar}---a
 permanently displayed menu stretching horizontally across the top of the
 frame.  The items of the menu bar are the subcommands of the fake

-``function key'' @code{menu-bar}, as defined by all the active keymaps.
+``function key'' @code{menu-bar}, as defined in the active keymaps.

 
   To add an item to the menu bar, invent a fake ``function key'' of your
 own (let's call it @var{key}), and make a binding for the key sequence
 
   To add an item to the menu bar, invent a fake ``function key'' of your
 own (let's call it @var{key}), and make a binding for the key sequence


@@ -2079,9 +2247,11 @@ at the end of the menu bar, following local menu items.
 @end defvar
 
 @defvar menu-bar-update-hook
 @end defvar
 
 @defvar menu-bar-update-hook

-This normal hook is run whenever the user clicks on the menu bar, before
-displaying a submenu.  You can use it to update submenus whose contents
-should vary.
+This normal hook is run by redisplay to update the menu bar contents,
+before redisplaying the menu bar.  You can use it to update submenus
+whose contents should vary.  Since this hook is run frequently, we
+advise you to ensure that the functions it calls do not take much time
+in the usual case.

 @end defvar
 
 @node Tool Bar
 @end defvar
 
 @node Tool Bar


@@ -2090,10 +2260,10 @@ should vary.
 
   A @dfn{tool bar} is a row of icons at the top of a frame, that execute
 commands when you click on them---in effect, a kind of graphical menu
 
   A @dfn{tool bar} is a row of icons at the top of a frame, that execute
 commands when you click on them---in effect, a kind of graphical menu

-bar.  Emacs supports tool bars starting with version 21.
+bar.

 
   The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
 
   The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})

-controls how may lines' worth of height to reserve for the tool bar.  A
+controls how many lines' worth of height to reserve for the tool bar.  A

 zero value suppresses the tool bar.  If the value is nonzero, and
 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
 contracts automatically as needed to hold the specified contents.
 zero value suppresses the tool bar.  If the value is nonzero, and
 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
 contracts automatically as needed to hold the specified contents.


@@ -2118,8 +2288,9 @@ tool bar bindings and have their normal meanings.  The @var{real-binding}
 in the item must be a command, not a keymap; in other words, it does not
 work to define a tool bar icon as a prefix key.
 
 in the item must be a command, not a keymap; in other words, it does not
 work to define a tool bar icon as a prefix key.
 

-  The @code{:help} property is meaningful, and specifies a ``help-echo''
-string to display while the mouse is on that item.
+  The @code{:help} property specifies a ``help-echo'' string to display
+while the mouse is on that item.  This is displayed in the same way as
+@code{help-echo} text properties (@pxref{Help display}).

 
   In addition, you should use the @code{:image} property;
 this is how you specify the image to display in the tool bar:
 
   In addition, you should use the @code{:image} property;
 this is how you specify the image to display in the tool bar:


@@ -2132,7 +2303,7 @@ one of them is used, depending on circumstances:
 
 @table @asis
 @item item 0
 
 @table @asis
 @item item 0

-Used when the iitem is enabled and selected.
+Used when the item is enabled and selected.

 @item item 1
 Used when the item is enabled and deselected.
 @item item 2
 @item item 1
 Used when the item is enabled and deselected.
 @item item 2


@@ -2142,6 +2313,87 @@ Used when the item is disabled and deselected.
 @end table
 @end table
 
 @end table
 @end table
 

+If @var{image} is a single image specification, Emacs draws the tool bar
+button in disabled state by applying an edge-detection algorithm to the
+image.
+
+The default tool bar is defined so that items specific to editing do not
+appear for major modes whose command symbol has a @code{mode-class}
+property of @code{special} (@pxref{Major Mode Conventions}).  Major
+modes may add items to the global bar by binding @code{[tool-bar
+@var{foo}]} in their local map.  It makes sense for some major modes to
+replace the default tool bar items completely, since not many can be
+accommodated conveniently, and the default bindings make this easy by
+using an indirection through @code{tool-bar-map}.
+
+@defvar tool-bar-map
+@tindex tool-bar-map
+By default, the global map binds @code{[tool-bar]} as follows:
+@example
+(global-set-key [tool-bar]
+               '(menu-item "tool bar" ignore
+                           :filter (lambda (ignore) tool-bar-map)))
+@end example
+@noindent
+Thus the tool bar map is derived dynamically from the value of variable
+@code{tool-bar-map} and you should normally adjust the default (global)
+tool bar by changing that map.  Major modes may replace the global bar
+completely by making @code{tool-bar-map} buffer-local and set to a
+keymap containing only the desired items.  Info mode provides an
+example.
+@end defvar
+
+There are two convenience functions for defining tool bar items, as
+follows.
+
+@defun tool-bar-add-item icon def key &rest props
+@tindex tool-bar-add-item
+This function adds an item to the tool bar by modifying
+@code{tool-bar-map}.  The image to use is defined by @var{icon}, which
+is the base name of an XPM, XBM or PBM image file to be located by
+@code{find-image}.  Given a value @samp{"exit"}, say, @file{exit.xpm},
+@file{exit.pbm} and @file{exit.xbm} would be searched for in that order
+on a color display.  On a monochrome display, the search order is
+@samp{.pbm}, @samp{.xbm} and @samp{.xpm}.  The binding to use is the
+command @var{def}, and @var{key} is the fake function key symbol in the
+prefix keymap.  The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+
+To define items in some local map, bind @code{tool-bar-map} with
+@code{let} around calls of this function:
+@example
+(defvar foo-tool-bar-map
+  (let ((tool-bar-map (make-sparse-keymap)))
+    (tool-bar-add-item @dots{})
+    @dots{}
+    tool-bar-map))
+@end example
+@end defun
+
+@defun tool-bar-add-item-from-menu command icon &optional map &rest props
+@tindex tool-bar-add-item-from-menu
+This function is a convenience for defining tool bar items which are
+consistent with existing menu bar bindings.  The binding of
+@var{command} is looked up in the menu bar in @var{map} (default
+@code{global-map}) and modified to add an image specification for
+@var{icon}, which is found in the same way as by
+@code{tool-bar-add-item}.  The resulting binding is then placed in
+@code{tool-bar-map}, so use this function only for global tool bar
+items.
+
+@var{map} must contain an appropriate keymap bound to
+@code{[menu-bar]}.  The remaining arguments @var{props} are additional
+property list elements to add to the menu item specification.
+@end defun
+
+@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
+This function is used for making non-global tool bar items.  Use it
+like @code{tool-bar-add-item-from-menu} except that @var{in-map}
+specifies the local map to make the definition in.  The argument
+@var{from-map} is like the @var{map} argument of
+@code{tool-bar-add-item-from-menu}.
+@end defun
+

 @tindex auto-resize-tool-bar
 @defvar auto-resize-tool-bar
 If this variable is non-@code{nil}, the tool bar automatically resizes to
 @tindex auto-resize-tool-bar
 @defvar auto-resize-tool-bar
 If this variable is non-@code{nil}, the tool bar automatically resizes to


@@ -2149,22 +2401,22 @@ show all defined tool bar items---but not larger than a quarter of the
 frame's height.
 @end defvar
 
 frame's height.
 @end defvar
 

-@tindex auto-raise-tool-bar-items
-@defvar auto-raise-tool-bar-items
+@tindex auto-raise-tool-bar-buttons
+@defvar auto-raise-tool-bar-buttons

 If this variable is non-@code{nil}, tool bar items display
 in raised form when the mouse moves over them.
 @end defvar
 
 If this variable is non-@code{nil}, tool bar items display
 in raised form when the mouse moves over them.
 @end defvar
 

-@tindex tool-bar-item-margin
-@defvar tool-bar-item-margin
+@tindex tool-bar-button-margin
+@defvar tool-bar-button-margin

 This variable specifies an extra margin to add around tool bar items.
 This variable specifies an extra margin to add around tool bar items.

-The value is an integer, a number of pixels.  The default is 1.
+The value is an integer, a number of pixels.  The default is 4.

 @end defvar
 
 @end defvar
 

-@tindex tool-bar-item-relief
-@defvar tool-bar-item-relief
+@tindex tool-bar-button-relief
+@defvar tool-bar-button-relief

 This variable specifies the shadow width for tool bar items.
 This variable specifies the shadow width for tool bar items.

-The value is an integer, a number of pixels.  The default is 3.
+The value is an integer, a number of pixels.  The default is 1.

 @end defvar
 
   You can define a special meaning for clicking on a tool bar item with
 @end defvar
 
   You can define a special meaning for clicking on a tool bar item with


@@ -2201,21 +2453,22 @@ put it in a particular place among the menu's existing items.  If you
 use @code{define-key} to add the item, it normally goes at the front of
 the menu.  To put it elsewhere in the menu, use @code{define-key-after}:
 
 use @code{define-key} to add the item, it normally goes at the front of
 the menu.  To put it elsewhere in the menu, use @code{define-key-after}:
 

-@defun define-key-after map key binding after
+@defun define-key-after map key binding &optional after

 Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after
 the binding for the event @var{after}.  The argument @var{key} should be
 of length one---a vector or string with just one element.  But
 @var{after} should be a single event type---a symbol or a character, not
 a sequence.  The new binding goes after the binding for @var{after}.  If
 Define a binding in @var{map} for @var{key}, with value @var{binding},
 just like @code{define-key}, but position the binding in @var{map} after
 the binding for the event @var{after}.  The argument @var{key} should be
 of length one---a vector or string with just one element.  But
 @var{after} should be a single event type---a symbol or a character, not
 a sequence.  The new binding goes after the binding for @var{after}.  If

-@var{after} is @code{t}, then the new binding goes last, at the end of
-the keymap.
+@var{after} is @code{t} or is omitted, then the new binding goes last, at
+the end of the keymap.  However, new bindings are added before any
+inherited keymap.

 
 Here is an example:
 
 @example
 (define-key-after my-menu [drink]
 
 Here is an example:
 
 @example
 (define-key-after my-menu [drink]

-                  '("Drink" . drink-command) 'eat)
+  '("Drink" . drink-command) 'eat)

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -2231,3 +2484,7 @@ menu of Shell mode, after the item @code{break}:
   [work] '("Work" . work-command) 'break)
 @end example
 @end defun
   [work] '("Work" . work-command) 'break)
 @end example
 @end defun

+
+@ignore
+   arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
+@end ignore