Eliding most of distutils and Carbon from the global module index

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Eliding most of distutils and Carbon from the global module index

Skip Montanaro-3

The global module index contains around 360 entries.  46 of them are for
various modules in the distutils package.  Another 24 are for Carbon (Mac)
modules.  I think almost all those references come from lines in
Doc/dist/dist.tex or Doc/mac/toolbox.tex like:

    \declaremodule{standard}{distutils.core}

or

    \declaremodule{standard}{Carbon.CF}

I think many/most of those modules could be omitted from the module index
without major problems.  The question is how to do that?  Should I

    * remove the \declaremodule lines from the .tex files

    * redefine the \declaremodule macro to accept an optional arg that can
      suppress the generation of an index entry

    * define a new macro (\declaremodulenoindex?) that does everything
      the current one does except the index entry dance

?  I'd like to do something.  Take a look at the docs for distutils.debug:

    http://www.python.org/dev/doc/devel/dist/module-distutils.debug.html

and these for Carbon.CF:

    http://www.python.org/dev/doc/devel/mac/module-Carbon.CF.html

Hardly seems worth mentioning in the module index at all, let alone on par
with sys, os, math, etc.

Point me in the right direction and I'll take care of the rest.

Skip
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Eliding most of distutils and Carbon from the global module index

Fred Drake-3
On Thursday 08 December 2005 13:57, [hidden email] wrote:
 > The global module index contains around 360 entries.  46 of them are for
 > various modules in the distutils package.  Another 24 are for Carbon (Mac)
 > modules.  I think almost all those references come from lines in
 > Doc/dist/dist.tex or Doc/mac/toolbox.tex like:
 >
 >     \declaremodule{standard}{distutils.core}
 >
 > or
 >
 >     \declaremodule{standard}{Carbon.CF}

That's correct.  That's not the only thing these lines are used to do,
however.

 > I think many/most of those modules could be omitted from the module index
 > without major problems.  The question is how to do that?  Should I
 >
 >     * remove the \declaremodule lines from the .tex files

No.

 >     * redefine the \declaremodule macro to accept an optional arg that can
 >       suppress the generation of an index entry

No.

 >     * define a new macro (\declaremodulenoindex?) that does everything
 >       the current one does except the index entry dance

No.

 > ?  I'd like to do something.  Take a look at the docs for distutils.debug:
 >
 >     http://www.python.org/dev/doc/devel/dist/module-distutils.debug.html
 >
 > and these for Carbon.CF:
 >
 >     http://www.python.org/dev/doc/devel/mac/module-Carbon.CF.html
 >
 > Hardly seems worth mentioning in the module index at all, let alone on par
 > with sys, os, math, etc.

It should be easy to remove the distutils modules simply by editing the
command used to generate html/modindex.html in Doc/Makefile.

Dealing with the Carbon modules may be more difficult.  Perhaps adding an
"exclude" filter to Doc/tools/mkmodindex would be sufficient.  It would need
to be set from the command line.

In the long run, though, we really just need to complete the documentation for
those modules without sufficient documentation.  Patches welcome.  :-)


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig