GNU bug report logs - #7755
24.0.50; Document that you can apply a keyword to a menu submenu

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7755 in the body.
You can then email your comments to 7755 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; Document that you can apply a keyword to a menu submenu
Date: Wed, 29 Dec 2010 09:24:56 -0800

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'
 

Message #8 received at 7755 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7755 <at> debbugs.gnu.org
Subject: Re: bug#7755: 24.0.50; Document that you can apply a keyword to a
 menu submenu
Date: Fri, 11 Oct 2019 22:29:01 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

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

I've now documented this in Emacs 27.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.