2.8.1. Building documentation
To build the documentation, you will need to check out the trunk of the
argouml-documentation project. This contains most of the tools you will
need as well as the source code of the manuals.
None of the other ArgoUML source directories are needed if you are just
building the documentation.
The subdirectories
trunk/src/manual, and
trunk/src/quickguide
contain the source code for each book.
The subdirectory
trunk/src/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 ('docs') 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 can use a specific
target for the document, format, and translation that you are working with.
The manual and quickguide contain multiple translations into different
spoken languages. All of the text for all translations is in the same
source code file, and a DocBook process called 'profiling' separates the
text into the different languages when the documentation is generated.
The build.xml file makes use of the Ant 'macrodef' task. This is used to
create parameterised targets for building different documents in different
translations. It is very helpful when there are many similar targets.
If you are working with the the build file, it suggested that
you make yourself familiar with the macrodef task
before going further.
The build process for a given target does the following:
The 'init' target always runs first, this checks that all of the
necessary tools are available.
Next, the 'prepare' target runs. This sets up some common
properties to make things a bit easier later on, and also
generates the custom stylesheets that are used to place the
ArgoUML branding on the documents.
Next, the language-specific 'xxxxx-profile-yy' target runs, where
xxxxx is the document, and yy is the language code. The work of the
target is done by a macrodef called 'profile'. The profiling
process does a replacement to update the version information in
the source files, then filters the source file into only one
language based on the lang="yy" attributes of the xml tags.
Next the specific target for the output format runs. In the case
of the two html outputs (create-htmlchunked and create-htmlsingl),
this involves using passing the source code through one stylesheet
which creates the html formatted output, then copying the images
into the output directory.
In the case of the PDF output, two stylesheets are run, followed by
FOP (Formatting Objects Processor), which does some special
manipulations for images in pdf files using the jimi library.
Licensing forbids us from supplying Jimi in the repository,
so you have to download it yourself
(http://java.sun.com/products/jimi/), and copy it
to
argouml-documentation\tools\lib\JimiProClasses.zip.
Failing to provide the Jimi library will result in warnings during
the build and poor or missing graphics in the pdf output.
Finally, (and only in the case of the overall targets) the 'tidy'
target is run which deletes intermediate files created during the
build process.
The files
manual/manual-generated.xmlmanual/manual-generated-yy.xmlmanual/manual.xml
C:\Work\argouml-documentation>build tidy
to explicitly delete the intermediate files before starting.
The 'clean' target deletes all generated files, including the output
files.
