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 12246f0..59e2e19 100644 (file)
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -1,6 +1,6 @@
 @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, 1999, 2000
+@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
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/keymaps


@@ -10,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}.


@@ -103,16 +103,19 @@ representation; it is also convenient to use @code{kbd}:
 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
 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:
+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"
 
 @example
 (kbd "C-x") @result{} "\C-x"
 (kbd "C-x C-f") @result{} "\C-x\C-f"

-(kbd "C-c C-c") @result{} "\C-c\C-c"

 (kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
 (kbd "X") @result{} "X"
 (kbd "RET") @result{} "\^M"
 (kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
 (kbd "X") @result{} "X"
 (kbd "RET") @result{} "\^M"

-(kbd "C-c 3") @result{} "\C-c3"
+(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
 
 @end example
 @end defmac
 


@@ -144,7 +147,8 @@ 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.
+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
 
 @item @var{char-table}
 If an element of a keymap is a char-table, it counts as holding


@@ -198,24 +202,29 @@ lisp-mode-map
 @end group
 @group
 (keymap
 @end group
 @group
 (keymap

- ;; @key{TAB}
- (9 . lisp-indent-line)
+ (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
  (27 keymap
      ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
 @end group
 @group
  (27 keymap
      ;; @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
 
 @end group
 @end example
 


@@ -251,17 +260,15 @@ satisfies @code{keymapp}.
 @c ??? This should come after make-sparse-keymap
 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap.  That keymap
 @c ??? This should come after make-sparse-keymap
 @defun make-keymap &optional prompt
 This function creates and returns a new full keymap.  That keymap

-contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
-128 slots are for defining all the @acronym{ASCII} characters, the next 128
-slots are for 8-bit European characters, and each one of the final 128
-slots is for one character set of non-@acronym{ASCII} characters supported by
-Emacs.  The new keymap initially binds all these characters to
-@code{nil}, and does not bind any other kind of event.
+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
 
 @end group
 @end example
 


@@ -449,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


@@ -509,6 +516,7 @@ 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:
 it creates a sparse keymap and stores it as @var{symbol}'s function
 definition.  Subsequently binding a key sequence to @var{symbol} will
 This function prepares @var{symbol} for use as a prefix key's binding:
 it creates a sparse keymap and stores it as @var{symbol}'s function
 definition.  Subsequently binding a key sequence to @var{symbol} will


@@ -529,41 +537,46 @@ string for the keymap.  The prompt string should be given 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.  Modes for emulation can specify additional
-active keymaps through the variable @code{emulation-mode-map-alists}.
-
-  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


@@ -572,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.


@@ -591,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


@@ -671,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.
 


@@ -698,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


@@ -755,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.
 


@@ -977,9 +990,12 @@ 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
+@defun current-active-maps &optional olp

 This returns the list of keymaps that would be used by the command
 This returns the list of keymaps that would be used by the command

-loop in the current circumstances to look up a key sequence.
+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
 @end defun
 
 @defun local-key-binding key &optional accept-defaults


@@ -1102,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


@@ -1191,7 +1208,7 @@ 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
 default global map.
 
   The function @code{substitute-key-definition} scans a keymap for

-keys that have a certain binding and rebind them with a different
+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}).
 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}).


@@ -1255,9 +1272,10 @@ 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
 
 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
 digits to run @code{digit-argument}, and @kbd{-} to run


@@ -1324,7 +1342,7 @@ this by making these two command-remapping bindings in its keymap:
 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
 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-mode-map},
+@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}.
 
 so instead of running @code{kill-line}, Emacs runs
 @code{my-kill-line}.
 


@@ -1337,15 +1355,16 @@ Remapping only works through a single level.  In other words,
 
 @noindent
 does not have the effect of remapping @code{kill-line} into
 
 @noindent
 does not have the effect of remapping @code{kill-line} into

-@code{my-other-kill-line}.  If an ordinary key binding specifies 
+@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
 @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}, given the
-current active keymaps.  If @var{command} is not remapped (which is
-the usual situation), the function returns @code{nil}.
+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
 @end defun
 
 @node Key Binding Commands


@@ -1383,7 +1402,7 @@ 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.
 
 @cindex non-@acronym{ASCII} text in keybindings
 set point where you click.
 
 @cindex non-@acronym{ASCII} text in keybindings


@@ -1409,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}


@@ -1499,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.
 


@@ -1517,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))


@@ -1541,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


@@ -1572,6 +1591,8 @@ 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.
 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.
 
 This function is the cleanest way to examine all the bindings
 in a keymap.


@@ -1580,7 +1601,7 @@ in a keymap.
 @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
 @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

-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


@@ -1588,7 +1609,7 @@ 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
+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.
 
 maps searched are @var{keymap} and the global keymap.  If @var{keymap}
 is a list of keymaps, only those keymaps are searched.
 


@@ -1598,11 +1619,12 @@ 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
 entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
 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 @acronym{ASCII} characters (or meta variants of @acronym{ASCII}

-characters) are preferred to all other key sequences.
+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
 
 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
 follow indirect keymap bindings.  This makes it possible to search for


@@ -1623,7 +1645,7 @@ other command.  However, if @var{no-remap} is non-@code{nil}.
 @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.


@@ -1643,6 +1665,10 @@ For example, in the default global map, the characters @samp{@key{SPC}
 @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}.
 @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}.

+
+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


@@ -1681,8 +1707,9 @@ 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},
 
 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} or @code{define-prefix-command}
-(@pxref{Creating Keymaps}).
+@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},
 
 @defun keymap-prompt keymap
 This function returns the overall prompt string of @var{keymap},


@@ -1722,7 +1749,7 @@ menu.  It should be short---preferably one to three words.  It should
 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
 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 Gtk+ support.@footnote{In this case, the text is first
+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.}
 
 encoded using the @code{utf-8} coding system and then rendered by the
 toolkit as it sees fit.}
 


@@ -1903,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"


@@ -2023,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


@@ -2073,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


@@ -2107,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


@@ -2170,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


@@ -2248,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


@@ -2259,7 +2260,7 @@ 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})
 controls how many lines' worth of height to reserve for the tool bar.  A
 
   The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
 controls how many lines' worth of height to reserve for the tool bar.  A


@@ -2389,7 +2390,7 @@ property list elements to add to the menu item specification.
 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
 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} si like the @var{map} argument of
+@var{from-map} is like the @var{map} argument of

 @code{tool-bar-add-item-from-menu}.
 @end defun
 
 @code{tool-bar-add-item-from-menu}.
 @end defun