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

Previous Next

Full log

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'
 

Previous Next

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