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

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

[Drew Adams]

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'

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 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.

Could you suggest a text for the manual to document this?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Drew Adams]

> Could you suggest a text for the manual to document this?

Doing this quickly.  Modify as you see fit.

In node `Extended Menu Items' we say:

 To define a real menu item which can be selected,
 the extended format binding looks like this:

     (menu-item ITEM-NAME REAL-BINDING
         . ITEM-PROPERTY-LIST)

 Here, ITEM-NAME is an expression which evaluates to
 the menu item string.  Thus, the string need not be
 a constant.  The third element, REAL-BINDING, is the
 command to execute.  The tail of the list,
 ITEM-PROPERTY-LIST, has the form of a property list
 which contains other information.

The last paragraph could be changed to indicate that
REAL-BINDING can be a command or a menu keymap (but
not a keymap-variable symbol).  Something like this
perhaps:

 Here, ITEM-NAME is an expression which evaluates to
 the menu item string.  Thus, the string need not be
 a constant.

 The third element, REAL-BINDING, is the command to
 execute or a menu keymap (but not a keymap-variable
 symbol).  If it is a menu keymap, that is, a keymap
 that has a prompt string, then ITEM-NAME is the
 name that appears for the submenu in its parent menu.
 
 The tail of the list, ITEM-PROPERTY-LIST, has the
 form of a property list that contains other information.

If you don't think that's clear enough (I do) then you
can add an example such as what I provided in the bug
report.

One thing I'm not clear on (haven't investigated): I'm
guessing that the keymap you provide here needs to be
a menu keymap, that is, a keymap with a prompt string.
Dunno whether that's true.  If not, remove mention of
that.

Whether that's actually needed or just possible, when
it happens what's the relation between the prompt
string and ITEM-NAME?  I'm guessing that ITEM-NAME is
used for the submenu name that appears, and the prompt
string is not used in this context.

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Doing this quickly.  Modify as you see fit.

Thanks; I've now expanded the section a bit along the lines you suggest.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no