Scripts to generate vxl documentation using doxygen

See how_it_works.txt for an overview.

Requirements:
The scripts assume that the following can be run at the command line:
- cvs
- doxygen   (see www.doxygen.org)
- texi2html (see http://techinfo.org or www.mathematik.uni-kl.de/~obachman/Texi2html)
             - If not available the book documentation won't be built,
			   but the main scripts should still run without breaking.


Quick setup on Debian/Ubuntu:

aptitude update
aptitude safe-upgrade
aptitude install cvs doxygen texi2html build-essential linux-headers-`uname -r` graphviz netpbm

You need "netpbm" for the pstopnm convertion script and "graphviz" to make nice inheritance diagrams.
Although doxygen will still work without these.

Usage:
Arrange that the perl scripts in this directory are executable.
(eg "chmod +x *.pl" under unix).

You can then simply run:

./build_all_doc.pl -v $VXLSRC -f

to generate all the documentation and index in $VXLSRC/Doxy/html
(This assumes vxl_scripts is checked out into $VXLSRC. If it isn't,
 use the -s flag to indicate where vxl_scripts/doxy is).

Common parameters
-----------------
All the scripts take one or more of the following parameters:
-v VXLSRC  : Defines where to find the code (eg VXLSRC/vxl/vnl)
-s script_dir : Defines location of script directory
                (default is $vxlsrc/vcl_scripts/doxy)
-o OUTPUTDIR : Defines base output directory (default is $vxlsrc/Doxy)
               (html will be put in $OUTPUTDIR/html)
-l ctrl_file : Defines file containing list of libraries and dependencies, books,
			and packages. (Default is $script_dir/data/library_list.txt)
-u : Update each package from CVS and only build if changes occur
-f : Force build of everything (useful every now and again to keep things in sync).


To generate documentation for your own modules
----------------------------------------------

a) Check them out into $VXLSRC

  eg in our $VXLSRC we have
    - vcl
	  - vxl
	  - mul
	  - isbe_apm  (local package)
	  - isbe_qtools (local package)

b) Create a library_list.txt file, based on the one in the data directory,
   indicating the extra libraries you use.
c) Create a book_list.txt file, based on the one in the data directory,
   indicating the extra texi books you have written
d) Invoke

build_all_doc.pl -v $VXLSRC -l my_library_list.txt -o OUTPUTDIR [-f] [-u]

That's all there is to it.


Updating documentation on a webserver
-------------------------------------
The script update_webserver.pl is provided to allow you to easily update
stuff on a web server.  Basically it invokes build_all_doc.pl, but only
after it has first invoked checkout_packages.pl to ensure any new packages
you might be interested in have been checked out first.

This makes it easy to add a new package to the system and have its documentation
appear on the webserver (over-night if you invoke the script each night).

When a package is added to the repository, to make documentation
appear for it you should modify the library_list.txt file
The checkout_packages.pl tool will be used to make sure the package gets checked
out onto the webserver, so that its documentation can then be generated.

Possible improvements to be made:
---------------------------------
- Tidy up texi2html parameters - perhaps pass them in to the tools.

Debugging:
----------

Output of scripts often gets sent to $VXLSRC/Doxy/output - look at what is there.




 Authors
 -------
 These scripts were written by Tim Cootes (University of Manchester)
 based on a set of scripts originally written by Dave Cooper, with
 contributions from Ian Scott and Peter Vanroose.
