Login | Register
My pages Projects Community openCollabNet
2.8. Generating documentation
Prev Chapter 2. Building from source Next

2.8. Generating documentation

This describes how to generate the documentation for ArgoUML.

If you are in a hurry, here's the quick version: 

C:\Work>svn checkout -N http://argouml.tigris.org/svn/argouml/trunk/src/argouml-build argouml/src/argouml-app
C:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/documentation argouml/documentation
c:\Work>svn checkout http://argouml.tigris.org/svn/argouml/trunk/tools argouml/tools
C:\Work>set JAVA_HOME=C:\Programs\jdkwhatever
C:\Work>cd argouml\documentation
C:\Work\argouml\documentation>build docbook-xsl-get   (first time only)
C:\Work\argouml\documentation>build defaulthtml

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.

Prev Up Next
2.7. The JUnit test cases Home 2.9. Setting up Eclipse 3