This describes how to generate the documentation for ArgoUML.
If you are in a hurry, here's the quick version:
User Manual and Quick Guide - Command line
C:\Work>svn checkout http://argouml-documentation.tigris.org/svn/argouml-documentation/trunk argouml-documentation C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever C:\Work>cd argouml-documentation C:\Work\argouml-documentation>build htmlchunked-en
The build command in the last line is the build.bat or build.sh file in the current directory. Hence, on Linux, you type: ./build.sh
User Manual and Quick Guide - Eclipse
Download http://argouml.tigris.org/nonav/psf/argouml-doc-projectset.
File > Import > Team > Team Project
- Navigate to file and click finish.
Run > External Tools > Open External Tools Dialog... > Documentation manual-htmlchunked-en > Run
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.xml and manual/manual-generated-yy.xml are temporary files that only exists while processing the XML. If you are editing the XML be sure to edit the file manual/manual.xml and not the temporary files. If in doubt, run
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.