Update lispref/maps.texi

Ref http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00702.html

* doc/lispref/maps.texi (Standard Keymaps): General update.
Remove mode-specific maps, talk about the more general keymaps.
* doc/lispref/help.texi (Help Functions): Add vindex for Helper-help-map.
* doc/lispref/keymaps.texi (Active Keymaps): Minor rephrasing.
* admin/FOR-RELEASE: Related markup.

1 files changed, 122 insertions, 162 deletions

diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi
index 524eab2cffe..b303562028b 100644
--- a/doc/lispref/maps.texi
+++ b/doc/lispref/maps.texi
@@ -1,39 +1,40 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1993, 1999, 2001-2012  Free Software Foundation, Inc.
+@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/maps
 @node Standard Keymaps, Standard Hooks, Standard Errors, Top
 @appendix Standard Keymaps
-@cindex standard keymaps
+@cindex keymaps, standard
 
-The following symbols are used as the names for various keymaps.
-Some of these exist when Emacs is first started, others are
-loaded only when their respective mode is used.  This is not
-an exhaustive list.
+In this section we list some of the more general keymaps.  Many of
+these exist when Emacs is first started, but some are loaded only when
+the respective feature is accessed.
 
-Several keymaps are used in the minibuffer.  @xref{Completion Commands}.
-
-Almost all of these maps are used as local maps.  Indeed, of the modes
-that presently exist, only Vip mode and Terminal mode ever change the
-global keymap.
+There are many other, more specialized, maps than these; in particular
+those associated with major and minor modes.  The minibuffer uses
+several keymaps (@pxref{Completion Commands}).  For more details on
+keymaps, @pxref{Keymaps}.
 
+@c Don't list individual major mode keymaps here, only more general things.
+@c Only add vindex for things not covered elsewhere in this manual.
+@c Don't add xrefs to things covered in {Keymaps}.
 @table @code
-@item apropos-mode-map
-@vindex apropos-mode-map
-A sparse keymap for @code{apropos} buffers.
+@item 2C-mode-map
+A sparse keymap for subcommands of the prefix @kbd{C-x 6}.@*
+@xref{Two-Column,, Two-Column Editing, emacs, The GNU Emacs Manual}.
 
-@item Buffer-menu-mode-map
-@vindex Buffer-menu-mode-map
-A full keymap used by Buffer Menu mode.
+@item abbrev-map
+@vindex abbrev-map
+A sparse keymap for subcommands of the prefix @kbd{C-x a}.@*
+@xref{Defining Abbrevs,,, emacs, The GNU Emacs Manual}.
 
-@item c-mode-map
-@vindex c-mode-map
-A sparse keymap used by C mode.
+@item button-buffer-map
+A sparse keymap useful for buffers containing buffers.@*
+You may want to use this as a parent keymap.  @xref{Buttons}.
 
-@item command-history-map
-@vindex command-history-map
-A full keymap used by Command History mode.
+@item button-map
+A sparse keymap used by buttons.
 
 @item ctl-x-4-map
 A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
@@ -44,196 +45,155 @@ A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
 @item ctl-x-map
 A full keymap for @kbd{C-x} commands.
 
-@item custom-mode-map
-A full keymap for Custom mode.
-
-@item debugger-mode-map
-@vindex debugger-mode-map
-A full keymap used by Debugger mode.
-
-@item dired-mode-map
-@vindex dired-mode-map
-A full keymap for @code{dired-mode} buffers.
-
-@item edit-abbrevs-map
-@vindex edit-abbrevs-map
-A sparse keymap used in @code{edit-abbrevs}.
-
-@item edit-tab-stops-map
-@vindex edit-tab-stops-map
-A sparse keymap used in @code{edit-tab-stops}.
-
-@item electric-buffer-menu-mode-map
-@vindex electric-buffer-menu-mode-map
-A full keymap used by Electric Buffer Menu mode.
-
-@item electric-history-map
-@vindex electric-history-map
-A full keymap used by Electric Command History mode.
-
-@item emacs-lisp-mode-map
-@vindex emacs-lisp-mode-map
-A sparse keymap used by Emacs Lisp mode.
+@item ctl-x-r-map
+@vindex ctl-x-r-map
+A sparse keymap for subcommands of the prefix @kbd{C-x r}.@*
+@xref{Registers,,, emacs, The GNU Emacs Manual}.
 
 @item esc-map
 A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
 
-@item facemenu-menu
-@vindex facemenu-menu
-The sparse keymap that displays the Text Properties menu.
-
-@item facemenu-background-menu
-@vindex facemenu-background-menu
-The sparse keymap that displays the Background Color submenu of the Text
-Properties menu.
-
-@item facemenu-face-menu
-@vindex facemenu-face-menu
-The sparse keymap that displays the Face submenu of the Text Properties menu.
+@item facemenu-keymap
+A sparse keymap used for the @kbd{M-o} prefix key.
 
-@item facemenu-foreground-menu
-@vindex facemenu-foreground-menu
-The sparse keymap that displays the Foreground Color submenu of the Text
-Properties menu.
-
-@item facemenu-indentation-menu
-@vindex facemenu-indentation-menu
-The sparse keymap that displays the Indentation submenu of the Text
-Properties menu.
-
-@item facemenu-justification-menu
-@vindex facemenu-justification-menu
-The sparse keymap that displays the Justification submenu of the Text
-Properties menu.
-
-@item facemenu-special-menu
-@vindex facemenu-special-menu
-The sparse keymap that displays the Special Props submenu of the Text
-Properties menu.
-
-@item local-function-key-map
-The keymap for translating key sequences to preferred alternatives.@*
-If there are none, then it contains an empty sparse keymap.
-@xref{Translation Keymaps}.
+@item function-key-map
+The parent keymap of all @code{local-function-key-map} (q.v.) instances.
 
+@ignore
+@c Doesn't exist.
 @item fundamental-mode-map
 @vindex fundamental-mode-map
 The sparse keymap for Fundamental mode.@*
 It is empty and should not be changed.
+@end ignore
 
 @item global-map
 The full keymap containing default global key bindings.@*
 Modes should not modify the Global map.
 
-@item grep-mode-map
-@vindex grep-mode-map
-The keymap for @code{grep-mode} buffers.
+@item goto-map
+A sparse keymap used for the @kbd{M-g} prefix key.
 
 @item help-map
-The sparse keymap for the keys that follow the help character @kbd{C-h}.
-
-@item help-mode-map
-@vindex help-mode-map
-The sparse keymap for Help mode.
+A sparse keymap for the keys following the help character @kbd{C-h}.@*
+@xref{Help Functions}.
 
 @item Helper-help-map
-@vindex Helper-help-map
 A full keymap used by the help utility package.@*
-It has the same keymap in its value cell and in its function
-cell.
-
-@item Info-edit-map
-@vindex Info-edit-map
-A sparse keymap used by the @code{Info-edit} command.
-
-@item Info-mode-map
-@vindex Info-mode-map
-A sparse keymap containing Info commands.
+It has the same keymap in its value cell and in its function cell.
 
 @item input-decode-map
 The keymap for translating keypad and function keys.@*
 If there are none, then it contains an empty sparse keymap.
 @xref{Translation Keymaps}.
 
-@item isearch-mode-map
-@vindex isearch-mode-map
-A keymap that defines the characters you can type within incremental
-search.
-
 @item key-translation-map
 A keymap for translating keys.  This one overrides ordinary key
 bindings, unlike @code{local-function-key-map}.  @xref{Translation
 Keymaps}.
 
-@item kmacro-map
-@vindex kmacro-map
-A sparse keymap for keys that follows the @kbd{C-x C-k} prefix
-search.
-
-@item lisp-interaction-mode-map
-@vindex lisp-interaction-mode-map
-A sparse keymap used by Lisp Interaction mode.
+@item kmacro-keymap
+@vindex kmacro-keymap
+A sparse keymap for keys that follows the @kbd{C-x C-k} prefix search.@*
+@xref{Keyboard Macros,,, emacs, The GNU Emacs Manual}.
 
-@item lisp-mode-map
-@vindex lisp-mode-map
-A sparse keymap used by Lisp mode.
-
-@item menu-bar-edit-menu
-@vindex menu-bar-edit-menu
-The keymap which displays the Edit menu in the menu bar.
+@item local-function-key-map
+The keymap for translating key sequences to preferred alternatives.@*
+If there are none, then it contains an empty sparse keymap.
+@xref{Translation Keymaps}.
 
 @item menu-bar-file-menu
+@itemx menu-bar-edit-menu
+@itemx menu-bar-options-menu
+@itemx global-buffers-menu-map
+@itemx menu-bar-tools-menu
+@itemx menu-bar-help-menu
+@cindex menu bar keymaps
 @vindex menu-bar-file-menu
-The keymap which displays the File menu in the menu bar.
-
-@item menu-bar-help-menu
-@vindex menu-bar-help-menu
-The keymap which displays the Help menu in the menu bar.
-
-@item menu-bar-mule-menu
-@vindex menu-bar-mule-menu
-The keymap which displays the Mule menu in the menu bar.
-
-@item menu-bar-search-menu
-@vindex menu-bar-search-menu
-The keymap which displays the Search menu in the menu bar.
-
-@item menu-bar-tools-menu
+@vindex menu-bar-options-menu
+@vindex global-buffers-menu-map
 @vindex menu-bar-tools-menu
-The keymap which displays the Tools menu in the menu bar.
+@vindex menu-bar-help-menu
+These keymaps display the main, top-level menus in the menu bar.@*
+Some of them contain sub-menus.  For example, the Edit menu contains
+@code{menu-bar-search-menu}, etc.  @xref{Menu Bar}.
+@ignore
+TODO list all submenus?
+There are probably too many, and it would not be useful to do so, eg:
+The Edit menu includes @code{yank-menu}, @code{menu-bar-search-menu},
+@code{menu-bar-replace-menu}, @code{menu-bar-goto-menu},
+@code{menu-bar-bookmark-map}, and @code{facemenu-menu}.
+There is also mule-menu-keymap, set-coding-system-map,
+setup-language-environment-map, describe-language-environment-map, 
+menu-bar-epatch-menu, menu-bar-ediff-merge-menu, menu-bar-ediff-menu, etc.
+@end ignore
+
+@item minibuffer-inactive-mode-map
+A full keymap used in the minibuffer when it is not active.@*
+@xref{Minibuffer Edit,, Editing in the Minibuffer, emacs, The GNU Emacs Manual}.
+
+@item mode-line-coding-system-map
+@itemx mode-line-input-method-map
+@itemx mode-line-column-line-number-mode-map
+@vindex mode-line-coding-system-map
+@vindex mode-line-input-method-map
+@vindex mode-line-column-line-number-mode-map
+These keymaps control various areas of the mode line.@*
+@xref{Mode Line Format}.
 
 @item mode-specific-map
 The keymap for characters following @kbd{C-c}.  Note, this is in the
-global map.  This map is not actually mode specific: its name was chosen
-to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
+global map.  This map is not actually mode-specific: its name was chosen
+to be informative in @kbd{C-h b} (@code{display-bindings}),
 where it describes the main use of the @kbd{C-c} prefix key.
 
-@item multi-query-replace-map
-A sparse keymap that extends @code{query-replace-map} for multi-buffer
-replacements.  @xref{Search and Replace, query-replace-map}.
+@c FIXME - don't mention this one?
+@item mouse-appearance-menu-map
+@vindex mouse-appearance-menu-map
+A sparse keymap used for the @kbd{S-mouse-1} key.
+
+@item mule-keymap
+The global keymap used for the @kbd{C-x @key{RET}} prefix key.
 
-@item occur-mode-map
-@vindex occur-mode-map
-A sparse keymap used by Occur mode.
+@item narrow-map
+@vindex narrow-map
+A sparse keymap for subcommands of the prefix @kbd{C-x n}.
+
+@item prog-mode-map
+The keymap used by Prog mode.@*
+@xref{Basic Major Modes}.
 
 @item query-replace-map
+@itemx multi-query-replace-map
 A sparse keymap used for responses in @code{query-replace} and related
 commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}.  The functions
 that use this map do not support prefix keys; they look up one event at a
-time.
+time.  @code{multi-query-replace-map} extends @code{query-replace-map}
+for multi-buffer replacements.  @xref{Search and Replace, query-replace-map}.
 
 @item search-map
-A sparse keymap that provides global bindings for search-related
-commands.
+A sparse keymap that provides global bindings for search-related commands.
 
-@item text-mode-map
-@vindex text-mode-map
-A sparse keymap used by Text mode.
+@item special-mode-map
+The keymap used by Special mode.@*
+@xref{Basic Major Modes}.
 
 @item tool-bar-map
-The keymap defining the contents of the tool bar.
+The keymap defining the contents of the tool bar.@*
+@xref{Tool Bar}.
+
+@item universal-argument-map
+@vindex universal-argument-map
+A sparse keymap used while processing @kbd{C-u}.@*
+@xref{Prefix Command Arguments}.
+
+@item vc-prefix-map
+The global keymap used for the @kbd{C-x v} prefix key.
+
+@item x-alternatives-map
+@vindex x-alternatives-map
+@findex x-setup-function-keys
+A sparse keymap used to map certain keys under graphical frames.@*
+The function @code{x-setup-function-keys} uses this.
 
-@item view-mode-map
-@vindex view-mode-map
-A full keymap used by View mode.
 @end table