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

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

[Drew Adams]

emacs -Q
 
C-h i, choose Elisp
 
Search for autoload. The first occurrence is `Autoload Type', in
subsection `Programming Types'.
 
The second occurrence is `Autoloading', in subsection `Kinds of Forms'.
It is supposed to be a node on "Functions set up to load files
containing their real definitions" ("their" is not super clear).
 
So the main menu entry for `Autoloading' is that node.
 
Continuing to search in the top-level menu we come to `Autoload' in
subsection `Loading'.
 
So we see that there are at least 3 nodes with very similar node names:
`Autoload Type', `Autoloading', and `Autoload'.  The first part of this
bug is that the names should be more specific, referring to the topics
of their relative subsections or some other specificity.
 
Next, follow the menu link to node `Autoloading'.  It is not, as the
main menu said, a node that describes or explains "Functions set up to
load files containing their real definitions".  It is a node that is
nearly vacuous of content.  It simply gives some general blah-blah about
autoloading and then sends you off to node `Autoload'.  So the second
part of this bug is to clean this up - either get rid of this node or
DTRT wrt its purported topic (and rename it, since the name is too
general for the topic).
 
Following that link we finally get to node `Autoload', which is where
autoloading is explained.  There should be a top-level, main menu entry
to this node, and not just a link buried in some subsection (let along 3
links in 3 subsections).
 
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.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-01-03 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  value of $XMODIFIERS: nil
  locale-coding-system: cp1252
  default enable-multibyte-characters: t
 
Major mode: Info
 
Minor modes in effect:
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t
 
Recent input:
C-h i <tab> <tab> <tab> <tab> <tab> <return> C-s a 
u t o l o a d C-s <return> <return> l <help-echo> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<menu-bar> <help-menu> <send-emacs-bug-report>
 
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Composing main Info directory...done
Mark saved where search started
 
Load-path shadows:
c:/Emacs-24-2011-01-03/lisp/emacs-lisp/sregex hides
c:/Emacs-24-2011-01-03/lisp/obsolete/sregex
c:/Emacs-24-2011-01-03/lisp/pgg hides c:/Emacs-24-2011-01-03/lisp/obsolete/pgg
c:/Emacs-24-2011-01-03/lisp/pgg-pgp5 hides
c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-pgp5
c:/Emacs-24-2011-01-03/lisp/pgg-pgp hides
c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-pgp
c:/Emacs-24-2011-01-03/lisp/pgg-parse hides
c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-parse
c:/Emacs-24-2011-01-03/lisp/pgg-gpg hides
c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-gpg
c:/Emacs-24-2011-01-03/lisp/pgg-def hides
c:/Emacs-24-2011-01-03/lisp/obsolete/pgg-def
 
Features:
(shadow sort gnus-util mail-extr message rfc822 mml mml-sec mm-decode
mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mailabbrev mail-utils gmm-utils mailheader emacsbug
multi-isearch info easymenu dired regexp-opt tooltip ediff-hook vc-hooks
lisp-float-type mwheel dos-w32 disp-table ls-lisp w32-win w32-vars
tool-bar dnd fontset image fringe lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev button minibuffer faces cus-face files
text-properties overlay md5 base64 format env code-pages mule custom
widget hashtable-print-readable backquote make-network-process multi-tty
emacs)

bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,...

[Drew Adams]

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

Likewise `define-widget' and any others.  In sum the list in the manual should
be complete, so users need not guess what gets handled by an autoload cookie and
what does not.

bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,...

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 4 Jan 2011 15:03:07 -0800
> Cc: 
> 
> > 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.
> 
> Likewise `define-widget' and any others.  In sum the list in the manual should
> be complete, so users need not guess what gets handled by an autoload cookie and
> what does not.

The text sounds as if the list is exhaustive, so the only issue is
whether it is correct or not.

bug#7783: 24.0.50; (elisp) autoloading nodes, autoload cookie fordefine-globalized-minor-mode,...

[Drew Adams]

> > > 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.
> > 
> > Likewise `define-widget' and any others.  In sum the list 
> > in the manual should be complete, so users need not guess what
> > gets handled by an autoload cookie and what does not.
> 
> The text sounds as if the list is exhaustive, so the only issue is
> whether it is correct or not.

Sounds as if...maybe...sort of...depending on the reader.  I agree that that is
suggested.  But it would be clearer if we said explicitly that this is a
complete list.

But yes, my main concern is that the list be up-to-date (complete).

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Tue, 4 Jan 2011 13:34:08 -0800
> Cc: 
> 
> C-h i, choose Elisp
>  
> Search for autoload. The first occurrence is `Autoload Type', in
> subsection `Programming Types'.
>  
> The second occurrence is `Autoloading', in subsection `Kinds of Forms'.
> It is supposed to be a node on "Functions set up to load files
> containing their real definitions" ("their" is not super clear).
>  
> So the main menu entry for `Autoloading' is that node.
>  
> Continuing to search in the top-level menu we come to `Autoload' in
> subsection `Loading'.

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

> So we see that there are at least 3 nodes with very similar node names:
> `Autoload Type', `Autoloading', and `Autoload'.  The first part of this
> bug is that the names should be more specific, referring to the topics
> of their relative subsections or some other specificity.

"Autoload Type" sounds appropriate to me -- it is a subsection of
"Lisp Data Types".  "Autoloading" could be renamed as "Autoload
Forms", since it's in the "Kinds of Forms" section, and quite a few of
its siblings are named "SOME Forms".  As for "Autoload", I'm not sure
it's a good idea to rename it, since it describes the `autoload'
facility itself.  Suggestions for specific node/section names are
welcome.

> Next, follow the menu link to node `Autoloading'.  It is not, as the
> main menu said, a node that describes or explains "Functions set up to
> load files containing their real definitions".  It is a node that is
> nearly vacuous of content.  It simply gives some general blah-blah about
> autoloading and then sends you off to node `Autoload'.  So the second
> part of this bug is to clean this up - either get rid of this node or
> DTRT wrt its purported topic (and rename it, since the name is too
> general for the topic).

I see no problem with the current organization of the manual.  Manuals
are for human consumption, so they don't need to mention each feature
in only one place.  It is perfectly valid practice in manuals to
mention shortly something that is only tangentially related to the
current main topic, then refer the reader for details to where that
something is described in full.  In this case, it is in a separate
node so that a reader who is not interested could go to the next node
without descending through the menu.

> Following that link we finally get to node `Autoload', which is where
> autoloading is explained.  There should be a top-level, main menu entry
> to this node, and not just a link buried in some subsection (let along 3
> links in 3 subsections).

I see no need for having this in the _main_ menu (it is, of course,
present in the detailed menu, below, in the same node).  It is
impractical to have every single important concept in the main menu,
and still produce a manual of a reasonably deep structure.

Readers should use `i', not the main menu, to search for specific
subjects, that's why we try to invest a significant effort in having
good indexing.  And in this case, it _is_ good, I think, because it
lands you right on target.

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

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

[Drew Adams]

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

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

[Chong Yidong]

I've checked in a fix which states explicitly which forms are processed
specially by the autoload facility.  I agree with Eli that the current
organization of the nodes is fine, so that's left alone.