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

[Eli Zaretskii <eliz@gnu.org>]

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