bug#26428: 24.5; (elisp) Extended Menu Items: document same features for menus

[Drew Adams <drew.adams@oracle.com>]

I filed a bug a few years back to get the use of keywords documented for
separator lines.  That was done: in (elisp) `Menu Separators' we now
have this:

   You can use a longer form to specify keywords such as `:enable'
   and `:visible=' for a menu separator:

   (menu-item SEPARATOR-TYPE nil . ITEM-PROPERTY-LIST)

   For example:

     (menu-item "--" nil :visible (boundp 'foo))

After some fiddling, I found that the same is true for menus
(e.g. submenus).  This too should be documented - it is not obvious.

What is needed is to pass the keymap itself, not a variable whose value
is the keymap, as the REAL-BINDING.  E.g.:

(define-key diredp-menu-bar-operate-menu [multiple-dired]
  `(menu-item "Dired" ,diredp-multiple-dired-menu
    :visible (save-excursion
               (goto-char (point-min))
               (and (re-search-forward (dired-marker-regexp) nil t)
                    (re-search-forward (dired-marker-regexp) nil t)))))

It's not enough to use `diredp-multiple-dired-menu' as the second arg to
`menu-item'.  Its value needs to be passed as the second arg.

The way (elisp) Extended Menu Items is written, it seems to apply only
to menu items that are leaves, not to those that are submenu names.
Even the description of REAL-BINDING suggests this limitation ("the
command to execute").

Please document how to use :enable, :visible etc. with a (sub)menu.

In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'