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

From: Drew Adams <[email-masked]>
Date: Sat, 12 Dec 2020 14:01:38 -0800 (PST)

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