This describes how to generate the documentation for ArgoUML.
The chunked HTML versions of the Cookbook, Quick Guide, and User Manual are
built and the results are placed in:
C:\Work\argouml\build\documentation\defaulthtml\cookbook,
C:\Work\argouml\build\documentation\defaulthtml\quick-guide,
and
C:\Work\argouml\build\documentation\defaulthtml\manual
respectively.
2.8.1. Building documentation
To build the documentation, you will need to check out the whole
trunk/documentation directory.
as well as the
trunk/tools directory
which contains the tools needed (Ant, FOP, Saxon, etc) and the file
trunk/src/argouml-app/default.properties
which contains the current version and other project-wide settings.
None of the other ArgoUML source directories are needed if you are just
building the documentation.
The subdirectories
trunk/documentation/cookbook,
trunk/documentation/manual, and
trunk/documentation/quick-guide
each contain one of the three books.
The subdirectory
trunk/documentation/docbook-setup
contains two things.
It contains the configuration files that control how the generation is done.
It contains the XSL rules for all the generation.
The subdirectory
trunk/documentation/xxx/images
contains the required pictures for each book.
There are separate build targets available for each output format,
as well as a target that builds all possible output formats.
Use the command build -p to get a complete list
of targets.
For testing purposes while editing a manual, you probably want to
build just a single output format for the one manual that you are
working with. To suppress the building of the other manuals,
you can define the following properties in your
build.properties file:
skip-cookbook=true
skip-quickguide=true
skip-argomanual=true
When, in the trunk/documentation directory,
you run ./build.sh defaulthtml or one of the other targets
that builds the documentation,
all books are built.
What happens is (the target internal-dispatcher):
The
manual/argomanual.xml
is copied by ant to
manual/argomanual-generated.xml
while doing substitution of tokens:
(@VERSION@ to become the version as specified in
default.properties)
The file
manual/argomanual-generated.xml
is processed by the special
docbook-setup/create-imglist.xsl
XSL script that generates a list of included images.
All included images are copied.
The purpose of this is to avoid copying images not actually
used in the document.
The HTML is generated by processing the file
manual/argomanual-generated.xml.
The file
manual/argomanual-generated.xml is
a temporary file that only exists while processing the XML.
If you are editing the XML be sure to edit
the file
manual/argomanual.xml
and not the temporary file.