$Id: README_DocBuilder.txt,v 1.3 2001/04/05 17:12:07 tagg Exp $

README for DocBuilder Package

Nathaniel Tagg  (n.tagg1@physics.ox.ac.uk)
Oxford University
March, 2001

This package will build the documentation for whatever other classes
exist.

CAVEAT: This package does not excuse coders from documenting their 
        work.

How to use it when building your main (public) release:
-------------------------------------------------------
Make sure that setup_minossoft_<myhost> has been sourced.

 $ cd $MINOS_SOFT/minossoft/releases/development
 $ gmake DocBuilder.bin
 $ perl DocBuilder/DocBuilder.pl -public
 <... long wait ...>
 
Voila!  There now exists a complete directory tree in doc/html with
all of the source files for Minos compiled into html.  It contains:

   index.html             -> is a symlink to index_of_packages.html

   index_of_packages.html -> A list of all the packages the script
                             could find, along with any installed
                             macros.

   index_Blah.html        -> An index of all classes that were in the
			     Blah package directory tree. This file
                             also includes the inheritance diagrams!

   ClassIndex.html        -> An index of all classes available.

   BlahClass.html         -> Individual class.
   
   blah.gif               -> Any .gif or .png or .jpg files from
                             anywhere else are transcribed to the html
                             tree.  (HINT HINT: document your classes!)

   macros/blahmacro.C.html-> HTML-ized version of blahmacro.C
   


Options for use:
---------------
If you don't have write access to the main minossoft directory, just
lnkpkg or addpkg all the packages you want to be indexed in the
documentation, then run

 $ perl DocBuilder/DocBuilder.pl -private

from your test directory. WARNING: this will only build documentation 
for those packages that you have in your private test directory! 
It does not consult the public directory.  To get a complete build in
your private directory, you must do
	lnkpkg <pkg>
for each package you want documented.


Note that the ROOT classes are by default all referred to at the
master web-page at CERN.  If you have downloaded all the class
documentation onto your hard drive into $ROOTSYS/doc/html, then you
can have the pages refer to your local copy instead (i.e. the href
tags change from http://www.root.cern.ch/root/html to
file:///<$ROOTSYS>/doc/html).

$ perl DocBuilder.pl -public -laptop


By default, the script only creates pages that don't exist yet. To
force the documentation to be rebuilt completely, either delete the
doc/html folder, or use:

$ perl DocBuilder.pl -public -force


Notes: 
------ 
The 'docbin' executable is created simply in order to
have a binary with all the minossoft libraries linked in.  The macro
then loads _all_ shared libraries (i.e. all libBlah.so files)
dynamically at runtime.  This should allow all classes 

ROOT will report "corrupted file ..." warnings (and others).  The
reasons for this are unknown, but do not appear to harm the results
and can be ignored.

---Nathaniel


Version history:
1.1 - first release
1.2 - minor bug fixes
1.3 - added dynamic libraries at runtime. Minor bug fixes.