imenu and major modes

[Greg Hill]

I recently created a new major mode, half the purpose of which is to 
automatically add an imenu whenever members of a certain class of 
files are edited.

The section in the Emacs Lisp Reference Manual describing Imenu mode 
(which says "This section explains how to customize how Imenu finds 
the definitions of buffer portions for a particular major mode") was 
helpful, but it did not explain how to make the imenu appear in the 
menu bar in a new major mode.  By looking at the imenu.el source code 
I figured out that imenu-add-menubar-index would do the trick. 
(Actually I ended up using imenu-add-to-menubar.)

Then I sent the following suggestion to lisp-manual-bugs@gnu.org:

> It would be helpful if you made some mention of the function 
> imenu-add-menubar-index.
>
> Perhaps you could add a note to the effect that, in order to add an 
> imenu index to a new major mode, all you have to do is to set the 
> value of imenu-generic-expression AND call imenu-add-menubar-index 
> in the function that enables that mode, e.g.:
>
>   (setq imenu-generic-expression '(("Groups" "^G: \\([^ \t]*\\)$" 1)))
>   (imenu-add-menubar-index)


I received the following reply from Stallman:

> That function is actually for end users to call.  Modes should not
> call it themselves.


Does anyone have a clue what he meant by that, and what a major mode 
"should" do instead?

Thanks.

--Greg