Improve description of :advertised-binding in Lisp manual.

* doc/lispref/keymaps.texi (Menu Bar): Move most of the :advertised-binding
description to help.texi.

* doc/lispref/help.texi (Keys in Documentation): Mention :advertised-binding.

3 files changed, 24 insertions, 11 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index d20c4d19c3a..16a0696b9f9 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2012-04-17  Chong Yidong  <cyd@gnu.org>
+
+        * help.texi (Keys in Documentation): Mention :advertised-binding.
+
+        * keymaps.texi (Menu Bar): Move most of the :advertised-binding
+        description to help.texi.
+
 2012-04-16  Glenn Morris  <rgm@gnu.org>
 
         * processes.texi (Process Information, Input to Processes)
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 2575f5e5bd6..627197f09f1 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -348,6 +348,21 @@ This function scans @var{string} for the above special sequences and
 replaces them by what they stand for, returning the result as a string.
 This permits display of documentation that refers accurately to the
 user's own customized key bindings.
+
+@cindex advertised binding
+If a command has multiple bindings, this function normally uses the
+first one it finds.  You can specify one particular key binding by
+assigning an @code{:advertised-binding} symbol property to the
+command, like this:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+The @code{:advertised-binding} property also affects the binding shown
+in menu items (@pxref{Menu Bar}).  The property is ignored if it
+specifies a key binding that the command does not actually have.
 @end defun
 
   Here are examples of the special sequences:
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 65666217e16..f1d4690d470 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -2549,17 +2549,8 @@ 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
-@code{:advertised-binding} symbol property to the command.  For
-instance, the following tells Emacs to show @kbd{C-/} for the
-@code{undo} menu item:
-
-@smallexample
-(put 'undo :advertised-binding [?\C-/])
-@end smallexample
-
-@noindent
-If the @code{:advertised-binding} property specifies a key binding
-that the command does not actually have, it is ignored.
+@code{:advertised-binding} symbol property to the command.  @xref{Keys
+in Documentation}.
 
 @node Tool Bar
 @subsection Tool bars