Subject: RE: bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie for define-globalized-minor-mode,...

From: "Drew Adams" <[email-masked]>
Date: Wed, 5 Jan 2011 10:31:15 -0800

> I presume you searched with `s' or some such.  If so, it is unclear
> why you are doing that, since `i' is so much more efficient (in this
> case it instantly gets you to the right spot).  Using `s' should be
> Plan B, not the first attempt.  (And if Plan B succeeds, a bug report
> about bad indexing should follow.)

Don't worry so much about why I'm doing that.  I mentioned that only as part of
the bug report recipe, for _you_ to find the menu links I wanted to discuss.  I
could have mentioned `m' instead.  At first I in fact wrote "scroll down to..."
in the recipe.  The point was to have you see the context and find the
occurrences easily.

I use `i' always as my first resort, thank you.

(FWIW, I use `C-s' if I need to search in Info these days.  I use `s' only in
older Emacs versions that do not support `C-s' across nodes.)

> I see no problem with the current organization of the manual.

Good for you.

> > Finally, in node `Autoload' we say that these constructs 
> > are handled by cookies: 
> >  
> > "Function-defining forms" include `define-skeleton',
> > `define-derived-mode', `define-generic-mode' and 
> > `define-minor-mode' as well as `defun' and `defmacro'.
> >  
> > What about `define-globalized-minor-mode'?  If that is not handled
> > similarly, then that is a code bug - it should be.  If it is handled
> > similarly by a cookie then it should be included in the doc 
> > list.  Users should not need to consult the source code to try
> > to determine what an autoload cookie before
> > `define-globalized-minor-mode' will do.
> 
> I don't know anything about this part, sorry.  Sounds like a separate
> issue, anyway.

Separate from what?  This is the _reason_ for this bug report.

The doc about autoloading does not tell you the latest list of constructs that
are supported by autoload cookies.  See the Subject line for this report.

You say you know nothing about this; fine.
Let's hope that someone does and will DTRT.

Deciding whether to add an autoload cookie entails knowing how they are handled.
You need to know what a cookie will do for a `defcustom' or a top-level sexp
such as `(if...)'.  That's why such things are documented.

E.g., if `define-widget' is not handled specially (is treated essentially like
`(if...)'), then a programmer needs to know that, so s?he does not bother (in
most cases) to add an autoload cookie for `define-widget'.

Only certain defining forms are handled specially by autoload cookies, and they
are documented as such.  But my impression is that the list might not be
up-to-date.

To be _completely_ clear it would help for the doc to either also say explicitly
which of the defining forms are _not_ handled or else (better, and sufficient)
state clearly that the list is complete (exhaustive).