[Emacs-diffs] /srv/bzr/emacs/emacs-23 r99784: * keymaps.texi (Menu Bar): Document :advertised-binding property.

[Chong Yidong]

------------------------------------------------------------
revno: 99784
committer: Chong Yidong <address@hidden>
branch nick: emacs-23
timestamp: Sun 2010-04-25 17:50:34 -0400
message:
  * keymaps.texi (Menu Bar): Document :advertised-binding property.
modified:
  doc/lispref/ChangeLog
  doc/lispref/keymaps.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2010-04-25 21:21:51 +0000
+++ b/doc/lispref/ChangeLog     2010-04-25 21:50:34 +0000
@@ -1,5 +1,7 @@
 2010-04-25  Chong Yidong  <address@hidden>
 
+       * keymaps.texi (Menu Bar): Document :advertised-binding property.
+
        * functions.texi (Obsolete Functions): Document
        set-advertised-calling-convention.
 

=== modified file 'doc/lispref/keymaps.texi'
--- a/doc/lispref/keymaps.texi  2010-01-13 08:35:10 +0000
+++ b/doc/lispref/keymaps.texi  2010-04-25 21:50:34 +0000
@@ -2470,9 +2470,13 @@
 @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.  The items of the menu bar are the subcommands of the fake
-``function key'' @code{menu-bar}, as defined in the active keymaps.
+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.
 
   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
@@ -2490,13 +2494,6 @@
 from the keymaps that would be active if @code{overriding-local-map}
 were @code{nil}.  @xref{Active Keymaps}.
 
-  In order for a frame to display a menu bar, its @code{menu-bar-lines}
-parameter must be greater than zero.  Emacs uses just one line for the
-menu bar itself; if you specify more than one line, the other lines
-serve to separate the menu bar from the windows in the frame.  We
-recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{Layout
-Parameters}.
-
   Here's an example of setting up a menu bar item:
 
 @example
@@ -2535,8 +2532,8 @@
 @end example
 
 @noindent
address@hidden is the fake function key used by the global map for the
address@hidden menu bar item.  The main reason to suppress a global
+Here, @code{edit} is the fake function key used by the global map for
+the @samp{Edit} menu bar item.  The main reason to suppress a global
 menu bar item is to regain space for mode-specific items.
 
 @defvar menu-bar-final-items
@@ -2557,6 +2554,23 @@
 in the usual case.
 @end defvar
 
+Next to every menu bar item, Emacs displays a key binding that runs
+the same command (if such a key binding exists).  This serves as a
+convenient hint for users who do not know the key binding.  If a
+command has multiple bindings, Emacs normally displays the first one
+it finds.  You can specify one particular key binding by assigning an
address@hidden:advertised-binding} symbol property to the command.  For
+instance, the following tells Emacs to show @kbd{C-/} for the
address@hidden menu item:
+
address@hidden
+(put 'undo :advertised-binding [?\C-/])
address@hidden smallexample
+
address@hidden
+If the @code{:advertised-binding} property specifies a key binding
+that the command does not actually have, it is ignored.
+
 @node Tool Bar
 @subsection Tool bars
 @cindex tool bar