GNU bug report logs - #12628
24.2.50; doc of `easy-menu-define'

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 12628 in the body.
You can then email your comments to 12628 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.2.50; doc of `easy-menu-define'
Date: Fri, 12 Oct 2012 10:09:14 -0700

This doc is all the more important because the doc for nearly all of the
other `easy-menu-*' functions just punts and points back to this doc.
It needs to be clear, complete, and correct.
 
In practice, users have to read the source code and work their way
through low-level helper function `easy-menu-convert-item-1' to figure
out what a menu item really can be.  Not good.
 
1. AFAICT, there is nothing in the doc string that corresponds to use
cases like these, for MENU:
 
["--" t]
["--" nil nil]
 
The doc says that CALLBACK is a command or a _list_ to evaluate.
`t' is certainly not a list.
 
The doc also does not say anything about what CALLBACK is evaluated for,
so presumably it is only for its side effects and its value is not used
(?).  This should be made explicit - e.g., "CALLBACK is an expression
that is evaluated for its side effects."
 
2. What on earth is ARG here?  It needs to be described.
 
 "Alternatively, a menu item may have the form:
   [ NAME CALLBACK [ KEYWORD ARG ] ... ]"
 
3. Why isn't there anything about `easy-menu*' in the Elisp manual?  The
manual covers defining and modifying menus, but it doesn't cover the
standard "easy" way to do that defined by RMS.

In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600)
 of 2012-10-09 on DANI-PC
Bzr revision: 110489 monnier <at> iro.umontreal.ca-20121009163751-ui2zwwoaj8bqwj52
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'
 

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

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 12628 <at> debbugs.gnu.org
Subject: Re: bug#12628: 24.2.50; doc of `easy-menu-define'
Date: Wed, 24 Oct 2012 11:49:05 +0800

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

> 1. AFAICT, there is nothing in the doc string that corresponds to use
> cases like these, for MENU:
>  
> 2. What on earth is ARG here?  It needs to be described.
>  
> 3. Why isn't there anything about `easy-menu*' in the Elisp manual?  The
> manual covers defining and modifying menus, but it doesn't cover the
> standard "easy" way to do that defined by RMS.

Fixed in trunk.

Previous Next

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