[Emacs-diffs] /srv/bzr/emacs/trunk r107284: Update Keymaps chapter of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107284
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-15 00:41:16 +0800
message:
  Update Keymaps chapter of Lisp manual.
  
  * doc/emacs/keymaps.texi (Format of Keymaps): The CACHE component of keymaps
  was removed on 2009-09-10.  Update lisp-mode-map example.
  (Inheritance and Keymaps): Minor clarification.
  (Searching Keymaps): Remove out-of-place enumeration.
  (Key Lookup): Remove unnecessary example (one was already given in
  Format of Keymaps).
  (Changing Key Bindings): Update suppress-keymap example.
  (Menu Bar, Tool Bar): Copyedits.
  (Tool Bar): Update tool-bar-map example.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/keymaps.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-12 09:51:03 +0000
+++ b/admin/FOR-RELEASE 2012-02-14 16:41:16 +0000
@@ -204,7 +204,7 @@
 index.texi
 internals.texi    
 intro.texi        cyd
-keymaps.texi      
+keymaps.texi      cyd
 lists.texi        cyd
 loading.texi      cyd
 locals.texi       

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-12 09:51:03 +0000
+++ b/doc/lispref/ChangeLog     2012-02-14 16:41:16 +0000
@@ -1,3 +1,15 @@
+2012-02-14  Chong Yidong  <address@hidden>
+
+       * keymaps.texi (Format of Keymaps): The CACHE component of keymaps
+       was removed on 2009-09-10.  Update lisp-mode-map example.
+       (Inheritance and Keymaps): Minor clarification.
+       (Searching Keymaps): Remove out-of-place enumeration.
+       (Key Lookup): Remove unnecessary example (one was already given in
+       Format of Keymaps).
+       (Changing Key Bindings): Update suppress-keymap example.
+       (Menu Bar, Tool Bar): Copyedits.
+       (Tool Bar): Update tool-bar-map example.
+
 2012-02-12  Chong Yidong  <address@hidden>
 
        * debugging.texi (Debugger Commands): Continuing is now allowed

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-02-06 08:34:28 +0000
+++ b/doc/lispref/keymaps.texi  2012-02-14 16:41:16 +0000
@@ -173,13 +173,11 @@
 which is always a character or a symbol.  @xref{Classifying Events}.
 In this kind of binding, @var{binding} is a command.
 
address@hidden (@var{type} @var{item-name} @address@hidden@r{]} .@: 
@var{binding})
address@hidden (@var{type} @var{item-name} .@: @var{binding})
 This specifies a binding which is also a simple menu item that
-displays as @var{item-name} in the menu.  @var{cache}, if present,
-caches certain information for display in the menu.  @xref{Simple Menu
-Items}.
+displays as @var{item-name} in the menu.  @xref{Simple Menu Items}.
 
address@hidden (@var{type} @var{item-name} @var{help-string} 
@address@hidden@r{]} .@: @var{binding})
address@hidden (@var{type} @var{item-name} @var{help-string} .@: @var{binding})
 This is a simple menu item with help string @var{help-string}.
 
 @item (@var{type} menu-item .@: @var{details})
@@ -234,8 +232,9 @@
 @address@hidden @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
-C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
+keymap.  It defines bindings for @key{DEL}, @kbd{C-c C-z},
address@hidden, and @kbd{C-M-x} (the actual value also contains a menu
+binding, which is omitted here for the sake of brevity).
 
 @example
 @group
@@ -250,11 +249,8 @@
 @end group
 @group
  (27 keymap
-     ;; @address@hidden, treated as @address@hidden C-x}}
-     (24 . lisp-send-defun)
-     keymap
-     ;; @address@hidden, treated as @address@hidden C-q}}
-     (17 . indent-sexp))
+     ;; @address@hidden, treated as @address@hidden C-x}}
+     (24 . lisp-send-defun))
 @end group
 @group
  ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@@ -264,9 +260,8 @@
 @end group
 @group
  (27 keymap
-     ;; @address@hidden, treated as @address@hidden C-q}}
-     (17 . indent-sexp))
- (9 . lisp-indent-line))
+     ;; @address@hidden, treated as @address@hidden C-q}}
+     (17 . indent-sexp)))
 @end group
 @end example
 
@@ -441,10 +436,10 @@
 @var{maps}, and optionally inheriting from a parent keymap
 @var{parent}.  @var{maps} can be a single keymap or a list of more
 than one.  When looking up a key in the resulting new map, Emacs
-searches in each of the @var{maps}, and then in @var{parent}, stopping
-at the first match.  A @code{nil} binding in any one of @var{maps}
-overrides any binding in @var{parent}, but not a address@hidden binding
-in any other of the @var{maps}.
+searches in each of the @var{maps} in turn, and then in @var{parent},
+stopping at the first match.  A @code{nil} binding in any one of
address@hidden overrides any binding in @var{parent}, but it does not
+override any address@hidden binding in any other of the @var{maps}.
 @end defun
 
 @noindent For example, here is how Emacs sets the parent of
@@ -762,35 +757,23 @@
 @end lisp
 
 @noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.)  If the key sequence starts with a mouse event,
-or a symbolic prefix event followed by a mouse event, that event's
-position is used instead of point and the current buffer.  Mouse
-events on an embedded string use address@hidden text properties from
-that string instead of the buffer.
-
address@hidden
address@hidden
-The function finally found may be remapped
-(@pxref{Remapping Commands}).
-
address@hidden
-Characters that are bound to @code{self-insert-command} are translated
-according to @code{translation-table-for-input} before insertion.
-
address@hidden
address@hidden returns a list of the
-currently active keymaps at point.
-
address@hidden
-When a match is found (@pxref{Key Lookup}), if the binding in the
address@hidden and @var{find-in-any} are pseudo functions that search
+in one keymap and in an alist of keymaps, respectively.  (Searching a
+single keymap for a binding is called @dfn{key lookup}; see @ref{Key
+Lookup}.)  If the key sequence starts with a mouse event, or a
+symbolic prefix event followed by a mouse event, that event's position
+is used instead of point and the current buffer.  Mouse events on an
+embedded string use address@hidden text properties from that string
+instead of the buffer.
+
+  When a match is found (@pxref{Key Lookup}), if the binding in the
 keymap is a function, the search is over.  However if the keymap entry
 is a symbol with a value or a string, Emacs replaces the input key
 sequences with the variable's value or the string, and restarts the
 search of the active keymaps.
address@hidden enumerate
+
+  The function finally found might also be remapped.  @xref{Remapping
+Commands}.
 
 @node Controlling Active Maps
 @section Controlling the Active Keymaps
@@ -1088,21 +1071,9 @@
 binding is not executable as a command.
 @end table
 
-  In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol that leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap.  This map is the normal value
-of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
address@hidden
-
address@hidden
address@hidden
-(keymap (9 . lisp-indent-line)
-        (127 . backward-delete-char-untabify)
-        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
address@hidden group
address@hidden example
+  In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or
address@hidden
 
 @node Functions for Key Lookup
 @section Functions for Key Lookup
@@ -1472,23 +1443,21 @@
 example, suppressing @code{global-map} would make it impossible to use
 most of Emacs.
 
-Most often, @code{suppress-keymap} is used to initialize local
-keymaps of modes such as Rmail and Dired where insertion of text is not
-desirable and the buffer is read-only.  Here is an example taken from
-the file @file{emacs/lisp/dired.el}, showing how the local keymap for
-Dired mode is set up:
+This function can be used to initialize the local keymap of a major
+mode for which insertion of text is not desirable.  But usually such a
+mode should be derived from @code{special-mode} (@pxref{Basic Major
+Modes}); then its keymap will automatically inherit from
address@hidden, which is already suppressed.  Here is how
address@hidden is defined:
 
 @smallexample
 @group
-(setq dired-mode-map (make-keymap))
-(suppress-keymap dired-mode-map)
-(define-key dired-mode-map "r" 'dired-rename-file)
-(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "v" 'dired-view-file)
-(define-key dired-mode-map "e" 'dired-find-file)
-(define-key dired-mode-map "f" 'dired-find-file)
address@hidden
+(defvar special-mode-map
+  (let ((map (make-sparse-keymap)))
+    (suppress-keymap map)
+    (define-key map "q" 'quit-window)
+    @dots{}
+    map))
 @end group
 @end smallexample
 @end defun
@@ -2064,12 +2033,10 @@
 @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.  Note that it is
-not generally possible to display address@hidden text in menus.  It will
-work for keyboard menus and will work to a large extent when Emacs is
-built with the Gtk+ address@hidden this case, the text is first
-encoded using the @code{utf-8} coding system and then rendered by the
-toolkit as it sees fit.}
+describe the action of the command it corresponds to.  Note that not
+all graphical toolkits can display address@hidden text in menus
+(it will work for keyboard menus and will work to a large extent with
+the GTK+ toolkit).
 
   You can also supply a second string, called the help string, as follows:
 
@@ -2418,18 +2385,6 @@
 she should type the corresponding character---the one whose binding is
 that alternative.
 
address@hidden
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type.  The best convention to use is to make
-the character the first letter of the item string---that is something
-users will understand without being told.  We plan to change this; by
-the time you read this manual, keyboard menus may explicitly name the
-key for each alternative.
address@hidden ignore
-
-  This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
-
 @defvar menu-prompt-more-char
 This variable specifies the character to use to ask to see
 the next line of a menu.  Its initial value is 32, the code
@@ -2512,21 +2467,17 @@
 @subsection The Menu Bar
 @cindex menu bar
 
-  Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of
-the frame.  (In order for a frame to display a menu bar, its
address@hidden parameter must be greater than zero.
address@hidden Parameters}.)
-
-  The items of the menu bar are the subcommands of the fake ``function
-key'' @code{menu-bar}, as defined in the active keymaps.
+  On graphical displays, there is usually a @dfn{menu bar} at the top
+of each frame.  @xref{Menu Bars,,,emacs, The GNU Emacs Manual}.  Menu
+bar items are subcommands of the fake ``function key''
address@hidden, 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
 @code{[menu-bar @var{key}]}.  Most often, the binding is a menu keymap,
 so that pressing a button on the menu bar item leads to another menu.
 
-  When more than one active keymap defines the same fake function key
+  When more than one active keymap defines the same ``function key''
 for the menu bar, the item appears just once.  If the user clicks on
 that menu bar item, it brings up a single, combined menu containing
 all the subcommands of that item---the global subcommands, the local
@@ -2541,11 +2492,6 @@
 
 @example
 @group
-(modify-frame-parameters (selected-frame)
-                         '((menu-bar-lines . 2)))
address@hidden group
-
address@hidden
 ;; @r{Make a menu keymap (with a prompt string)}
 ;; @r{and make it the menu bar item's definition.}
 (define-key global-map [menu-bar words]
@@ -2618,20 +2564,17 @@
 @subsection Tool bars
 @cindex tool bar
 
-  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.
-
-  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
-zero value suppresses the tool bar.  If the value is nonzero, and
address@hidden is address@hidden, the tool bar expands and
-contracts automatically as needed to hold the specified contents.
-
-  If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, the user has to redraw the frame by entering
address@hidden
+  A @dfn{tool bar} is a row of clickable icons at the top of a frame,
+just below the menu bar.  @xref{Tool Bars,,,emacs, The GNU Emacs
+Manual}.
+
+  On each frame, the frame parameter @code{tool-bar-lines} 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
address@hidden is address@hidden, the tool bar expands
+and contracts automatically as needed to hold the specified contents.
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically.
 
   The tool bar contents are controlled by a menu keymap attached to a
 fake ``function key'' called @code{tool-bar} (much like the way the menu
@@ -2683,17 +2626,17 @@
 image.
 
 The @code{:rtl} property specifies an alternative image to use for
-right-to-left languages.  Only the Gtk+ version of Emacs supports this
+right-to-left languages.  Only the GTK+ version of Emacs supports this
 at present.
 
 Like the menu bar, the tool bar can display separators (@pxref{Menu
 Separators}).  Tool bar separators are vertical rather than
-horizontal, though, and only a single style is supported.  Separators
-are represented in the tool bar keymap in the same way as for the
-menu bar, i.e. using a @code{(menu-item "--"}) entry.  The Gtk+ and
-Nextstep tool bars render separators natively, otherwise Emacs selects
-a separator image that is appropriate for the display.  Note that tool
-bar separators do not support any properties, such as @code{:visible}.
+horizontal, though, and only a single style is supported.  They are
+represented in the tool bar keymap by @code{(menu-item "--")} entries;
+properties like @code{:visible} are not supported for tool bar
+separators.  Separators are rendered natively in GTK+ and Nextstep
+tool bars; in the other cases, they are rendered using an image of a
+vertical line.
 
 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}
@@ -2706,18 +2649,20 @@
 
 @defvar 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)))
+               `(menu-item ,(purecopy "tool bar") ignore
+                           :filter tool-bar-make-keymap))
 @end example
+
 @noindent
-Thus the tool bar map is derived dynamically from the value of variable
address@hidden 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.
+The function @code{tool-bar-make-keymap}, in turn, derives the actual
+tool bar map dynamically from the value of the variable
address@hidden  Hence, you should normally adjust the default
+(global) tool bar by changing that map.  Some major modes, such as
+Info mode, completely replace the global tool bar by making
address@hidden buffer-local and setting it to a different keymap.
 @end defvar
 
 There are two convenience functions for defining tool bar items, as