bug#7755: 24.0.50; Document that you can apply a keyword to a menu submenu

[Drew Adams]

emacs -Q
 
(See also related bug #6344.)
 
The doc for so-called extended menu items is misleading and incomplete.
 
1. As bug #6344 addresses, the doc does not indicate that you can use
`menu-item' and keywords for a non-selectable menu item.
 
2. The doc also does not indicate that you can use `menu-item' and
keywords for a submenu, as opposed to a menu item.
 
#2 is the subject of this bug report, but #1 and #2 should be addressed
 together.
 
The relevant doc is (elisp) `Extended Menu Items'.
 
What's missing is to explicitly state the following:
 
a. This is about submenus as well as menu items (no, a submenu is not a
   menu item).  This also means that the node name is not really
   appropriate.
 
b. The form for a submenu is the same:
   (menu-item ITEM-NAME REAL-BINDING . ITEM-PROPERTY-LIST)
 
   But the REAL-BINDING description needs to be changed.  This is
   incorrect:
   "The third element, REAL-BINDING, is the command to execute."
 
   REAL-BINDING can be a command or a keymap or nil.
 
c. If REAL-BINDING is a command, then you get a selectable menu item.
   If it is a keymap then you get a submenu.  If it is nil then you get
   a non-selectable menu item (e.g. a separator line).
 
All of this is particularly important wrt ITEM-PROPERTY-LIST, which BTW
needs to be renamed to something like KEYWORDS, since (i) it is a
_keyword_ list, not an arbitrary property list, and (ii) it is not
necessarily for a menu item, since REAL-BINDING can also be a keymap or
nil.
 
Without such doc changes, users will not know that they can use a
keyword such as :visible with a submenu or a separator item (to
remove it, in the case of :visible).
 
I discovered this only by trial and error and by examining the Emacs
source files.  Among the Emacs source files, AFAICT only 3 files use
:visible with a submenu, and for a total of only 5 submenus.
 
The 3 files: menu-bar.el, semantic.el, and gdb-mi.el. The 5 submenus:
`menu-bar-showhide-fringe-ind-menu', `menu-bar-showhide-fringe-menu',
`menu-bar-showhide-scroll-bar-menu', `menu-bar-showhide-tool-bar-menu',
`mule-menu-keymap', `edit-menu', `navigate-menu', `menu'.
 
IOW, this feature does not appear to be used often by Emacs developers,
which suggests that perhaps it is not well known.
 
I got the idea when looking for a good way to dynamically remove a
submenu that has only buffer-modifying commands from a popup menu
whenever the buffer is read-only.

I'm guessing that such a use case might be more common than the
actual uses in our sources of :visible with a submenu indicate.  Don't
we have any submenus that should be removed or disabled for a
read-only buffer, for example?

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-12-20 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'