[Emacs-diffs] /srv/bzr/emacs/trunk r107467: Update lispref/maps.texi

[Glenn Morris]

------------------------------------------------------------
revno: 107467
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-02-29 23:29:48 -0800
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/help.texi
  doc/lispref/keymaps.texi
  doc/lispref/maps.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-28 04:17:02 +0000
+++ b/admin/FOR-RELEASE 2012-03-01 07:29:48 +0000
@@ -209,7 +209,7 @@
 lists.texi        cyd
 loading.texi      cyd
 macros.texi       cyd
-maps.texi         
+maps.texi         rgm
 markers.texi      
 minibuf.texi      
 modes.texi        cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-29 08:11:23 +0000
+++ b/doc/lispref/ChangeLog     2012-03-01 07:29:48 +0000
@@ -1,3 +1,10 @@
+2012-03-01  Glenn Morris  <address@hidden>
+
+       * maps.texi (Standard Keymaps): General update.
+       Remove mode-specific maps, talk about the more general keymaps.
+       * help.texi (Help Functions): Add vindex for Helper-help-map.
+       * keymaps.texi (Active Keymaps): Minor rephrasing.
+
 2012-02-29  Glenn Morris  <address@hidden>
 
        * elisp.texi, vol1.texi, vol2.texi: Use "" quotes in menus.

=== modified file 'doc/lispref/help.texi'
--- a/doc/lispref/help.texi     2012-02-19 06:20:23 +0000
+++ b/doc/lispref/help.texi     2012-03-01 07:29:48 +0000
@@ -636,6 +636,7 @@
 options)}, and then provides assistance in finding out what the key
 bindings are, and what the mode is intended for.  It returns @code{nil}.
 
address@hidden Helper-help-map
 This can be customized by changing the map @code{Helper-help-map}.
 @end deffn
 

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2012-02-14 16:41:16 +0000
+++ b/doc/lispref/keymaps.texi  2012-03-01 07:29:48 +0000
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990-1994, 1998-2012  Free Software Foundation, 
Inc.
address@hidden Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/keymaps
 @node Keymaps, Modes, Command Loop, Top
@@ -686,7 +686,7 @@
   Emacs has other keymaps that are used in a different way---translating
 events within @code{read-key-sequence}.  @xref{Translation Keymaps}.
 
-  @xref{Standard Keymaps}, for a list of standard keymaps.
+  @xref{Standard Keymaps}, for a list of some standard keymaps.
 
 @defun current-active-maps &optional olp position
 This returns the list of active keymaps that would be used by the

=== modified file 'doc/lispref/maps.texi'
--- a/doc/lispref/maps.texi     2012-02-28 04:17:02 +0000
+++ b/doc/lispref/maps.texi     2012-03-01 07:29:48 +0000
@@ -1,39 +1,40 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990-1993, 1999, 2001-2012  Free Software 
Foundation, Inc.
address@hidden 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
address@hidden standard keymaps
-
-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.
-
-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.
-
address@hidden keymaps, standard
+
+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.
+
+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}.
+
address@hidden Don't list individual major mode keymaps here, only more general 
things.
address@hidden Only add vindex for things not covered elsewhere in this manual.
address@hidden Don't add xrefs to things covered in {Keymaps}.
 @table @code
address@hidden apropos-mode-map
address@hidden apropos-mode-map
-A sparse keymap for @code{apropos} buffers.
-
address@hidden Buffer-menu-mode-map
address@hidden Buffer-menu-mode-map
-A full keymap used by Buffer Menu mode.
-
address@hidden c-mode-map
address@hidden c-mode-map
-A sparse keymap used by C mode.
-
address@hidden command-history-map
address@hidden command-history-map
-A full keymap used by Command History mode.
address@hidden 2C-mode-map
+A sparse keymap for subcommands of the prefix @kbd{C-x address@hidden
address@hidden,, Two-Column Editing, emacs, The GNU Emacs Manual}.
+
address@hidden abbrev-map
address@hidden abbrev-map
+A sparse keymap for subcommands of the prefix @kbd{C-x address@hidden
address@hidden Abbrevs,,, emacs, The GNU Emacs Manual}.
+
address@hidden button-buffer-map
+A sparse keymap useful for buffers containing address@hidden
+You may want to use this as a parent keymap.  @xref{Buttons}.
+
address@hidden 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 @@
 @item ctl-x-map
 A full keymap for @kbd{C-x} commands.
 
address@hidden custom-mode-map
-A full keymap for Custom mode.
-
address@hidden debugger-mode-map
address@hidden debugger-mode-map
-A full keymap used by Debugger mode.
-
address@hidden dired-mode-map
address@hidden dired-mode-map
-A full keymap for @code{dired-mode} buffers.
-
address@hidden edit-abbrevs-map
address@hidden edit-abbrevs-map
-A sparse keymap used in @code{edit-abbrevs}.
-
address@hidden edit-tab-stops-map
address@hidden edit-tab-stops-map
-A sparse keymap used in @code{edit-tab-stops}.
-
address@hidden electric-buffer-menu-mode-map
address@hidden electric-buffer-menu-mode-map
-A full keymap used by Electric Buffer Menu mode.
-
address@hidden electric-history-map
address@hidden electric-history-map
-A full keymap used by Electric Command History mode.
-
address@hidden emacs-lisp-mode-map
address@hidden emacs-lisp-mode-map
-A sparse keymap used by Emacs Lisp mode.
address@hidden ctl-x-r-map
address@hidden ctl-x-r-map
+A sparse keymap for subcommands of the prefix @kbd{C-x address@hidden
address@hidden,,, emacs, The GNU Emacs Manual}.
 
 @item esc-map
 A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
 
address@hidden facemenu-menu
address@hidden facemenu-menu
-The sparse keymap that displays the Text Properties menu.
-
address@hidden facemenu-background-menu
address@hidden facemenu-background-menu
-The sparse keymap that displays the Background Color submenu of the Text
-Properties menu.
-
address@hidden facemenu-face-menu
address@hidden facemenu-face-menu
-The sparse keymap that displays the Face submenu of the Text Properties menu.
-
address@hidden facemenu-foreground-menu
address@hidden facemenu-foreground-menu
-The sparse keymap that displays the Foreground Color submenu of the Text
-Properties menu.
-
address@hidden facemenu-indentation-menu
address@hidden facemenu-indentation-menu
-The sparse keymap that displays the Indentation submenu of the Text
-Properties menu.
-
address@hidden facemenu-justification-menu
address@hidden facemenu-justification-menu
-The sparse keymap that displays the Justification submenu of the Text
-Properties menu.
-
address@hidden facemenu-special-menu
address@hidden facemenu-special-menu
-The sparse keymap that displays the Special Props submenu of the Text
-Properties menu.
-
address@hidden local-function-key-map
-The keymap for translating key sequences to preferred address@hidden
-If there are none, then it contains an empty sparse keymap.
address@hidden Keymaps}.
-
address@hidden facemenu-keymap
+A sparse keymap used for the @kbd{M-o} prefix key.
+
address@hidden function-key-map
+The parent keymap of all @code{local-function-key-map} (q.v.) instances.
+
address@hidden
address@hidden Doesn't exist.
 @item fundamental-mode-map
 @vindex fundamental-mode-map
 The sparse keymap for Fundamental address@hidden
 It is empty and should not be changed.
address@hidden ignore
 
 @item global-map
 The full keymap containing default global key address@hidden
 Modes should not modify the Global map.
 
address@hidden grep-mode-map
address@hidden grep-mode-map
-The keymap for @code{grep-mode} buffers.
address@hidden 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}.
-
address@hidden help-mode-map
address@hidden help-mode-map
-The sparse keymap for Help mode.
+A sparse keymap for the keys following the help character @address@hidden
address@hidden Functions}.
 
 @item Helper-help-map
address@hidden Helper-help-map
 A full keymap used by the help utility address@hidden
-It has the same keymap in its value cell and in its function
-cell.
-
address@hidden Info-edit-map
address@hidden Info-edit-map
-A sparse keymap used by the @code{Info-edit} command.
-
address@hidden Info-mode-map
address@hidden 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 address@hidden
 If there are none, then it contains an empty sparse keymap.
 @xref{Translation Keymaps}.
 
address@hidden isearch-mode-map
address@hidden 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}.
 
address@hidden kmacro-map
address@hidden kmacro-map
-A sparse keymap for keys that follows the @kbd{C-x C-k} prefix
-search.
-
address@hidden lisp-interaction-mode-map
address@hidden lisp-interaction-mode-map
-A sparse keymap used by Lisp Interaction mode.
-
address@hidden lisp-mode-map
address@hidden lisp-mode-map
-A sparse keymap used by Lisp mode.
-
address@hidden menu-bar-edit-menu
address@hidden menu-bar-edit-menu
-The keymap which displays the Edit menu in the menu bar.
address@hidden kmacro-keymap
address@hidden kmacro-keymap
+A sparse keymap for keys that follows the @kbd{C-x C-k} prefix address@hidden
address@hidden Macros,,, emacs, The GNU Emacs Manual}.
+
address@hidden local-function-key-map
+The keymap for translating key sequences to preferred address@hidden
+If there are none, then it contains an empty sparse keymap.
address@hidden Keymaps}.
 
 @item menu-bar-file-menu
address@hidden menu-bar-edit-menu
address@hidden menu-bar-options-menu
address@hidden global-buffers-menu-map
address@hidden menu-bar-tools-menu
address@hidden menu-bar-help-menu
address@hidden menu bar keymaps
 @vindex menu-bar-file-menu
-The keymap which displays the File menu in the menu bar.
-
address@hidden menu-bar-help-menu
address@hidden menu-bar-options-menu
address@hidden global-buffers-menu-map
address@hidden menu-bar-tools-menu
 @vindex menu-bar-help-menu
-The keymap which displays the Help menu in the menu bar.
-
address@hidden menu-bar-mule-menu
address@hidden menu-bar-mule-menu
-The keymap which displays the Mule menu in the menu bar.
-
address@hidden menu-bar-search-menu
address@hidden menu-bar-search-menu
-The keymap which displays the Search menu in the menu bar.
-
address@hidden menu-bar-tools-menu
address@hidden menu-bar-tools-menu
-The keymap which displays the Tools menu in the menu bar.
+These keymaps display the main, top-level menus in the menu address@hidden
+Some of them contain sub-menus.  For example, the Edit menu contains
address@hidden, etc.  @xref{Menu Bar}.
address@hidden
+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},
address@hidden, @code{menu-bar-goto-menu},
address@hidden, 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.
address@hidden ignore
+
address@hidden minibuffer-inactive-mode-map
+A full keymap used in the minibuffer when it is not address@hidden
address@hidden Edit,, Editing in the Minibuffer, emacs, The GNU Emacs Manual}.
+
address@hidden mode-line-coding-system-map
address@hidden mode-line-input-method-map
address@hidden mode-line-column-line-number-mode-map
address@hidden mode-line-coding-system-map
address@hidden mode-line-input-method-map
address@hidden mode-line-column-line-number-mode-map
+These keymaps control various areas of the mode address@hidden
address@hidden 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.
 
address@hidden multi-query-replace-map
-A sparse keymap that extends @code{query-replace-map} for multi-buffer
-replacements.  @xref{Search and Replace, query-replace-map}.
-
address@hidden occur-mode-map
address@hidden occur-mode-map
-A sparse keymap used by Occur mode.
address@hidden FIXME - don't mention this one?
address@hidden mouse-appearance-menu-map
address@hidden mouse-appearance-menu-map
+A sparse keymap used for the @kbd{S-mouse-1} key.
+
address@hidden mule-keymap
+The global keymap used for the @kbd{C-x @key{RET}} prefix key.
+
address@hidden narrow-map
address@hidden narrow-map
+A sparse keymap for subcommands of the prefix @kbd{C-x n}.
+
address@hidden prog-mode-map
+The keymap used by Prog address@hidden
address@hidden Major Modes}.
 
 @item query-replace-map
address@hidden 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.
 
address@hidden text-mode-map
address@hidden text-mode-map
-A sparse keymap used by Text mode.
address@hidden special-mode-map
+The keymap used by Special address@hidden
address@hidden Major Modes}.
 
 @item tool-bar-map
-The keymap defining the contents of the tool bar.
-
address@hidden view-mode-map
address@hidden view-mode-map
-A full keymap used by View mode.
+The keymap defining the contents of the tool address@hidden
address@hidden Bar}.
+
address@hidden universal-argument-map
address@hidden universal-argument-map
+A sparse keymap used while processing @address@hidden
address@hidden Command Arguments}.
+
address@hidden vc-prefix-map
+The global keymap used for the @kbd{C-x v} prefix key.
+
address@hidden x-alternatives-map
address@hidden x-alternatives-map
address@hidden x-setup-function-keys
+A sparse keymap used to map certain keys under graphical address@hidden
+The function @code{x-setup-function-keys} uses this.
+
 @end table