Document toolkit differences for menus

(Toolkit Differences): New node with text from Tim
Cross (tiny change) and Glenn Morris.

doc/lispref/ChangeLog

+2011-07-16  Lars Magne Ingebrigtsen  <larsi@gnus.org>
+
+	* keymaps.texi (Toolkit Differences): New node with text from Tim
+	Cross (tiny change) and Glenn Morris.
+
 2011-07-15  Andreas Schwab  <schwab@linux-m68k.org>
 
 	* help.texi (Keys in Documentation): Revert last change.

doc/lispref/keymaps.texi

@@ -2019,8 +2019,10 @@ an existing menu, you can specify its position in the menu using
                               various features.
 * Menu Separators::         Drawing a horizontal line through a menu.
 * Alias Menu Items::        Using command aliases in menu items.
+* Toolkit Differences::     Not all toolkits provide the same features.
 @end menu
 
+
 @node Simple Menu Items
 @subsubsection Simple Menu Items
 
@@ -2309,6 +2311,28 @@ itself).  To request this, give the alias symbol a non-@code{nil}
 causes menu items for @code{make-read-only} and @code{make-writable} to
 show the keyboard bindings for @code{toggle-read-only}.
 
+@node Toolkit Differences
+@subsubsection Toolkit Differences
+
+The various toolkits with which you can build Emacs do not all support
+the same set of features for menus.  Some code works as expected with
+one toolkit, but not under another.
+
+For example: menu actions or buttons in a top-level menu-bar.  The
+following works with the Lucid toolkit or on MS Windows, but not with
+GTK or Nextstep, where clicking on the item has no effect.
+
+@example
+(defun menu-action-greet ()
+   (interactive)
+   (message "Hello Emacs User!"))
+
+(defun top-level-menu ()
+  (interactive)
+  (define-key lisp-interaction-mode-map [menu-bar m]
+     '(menu-item "Action Button" menu-action-greet)))
+@end example
+
 @node Mouse Menus
 @subsection Menus and the Mouse