2.5. Migrating from Ant

Previously the JBoss DocBook system used Ant to perform builds. This meant that each DocBook subdirectory contained a build.xml file as follows:

<project name="Documentation" default="all.doc" basedir=".">

    <property name="pdf.name" value="jboss-mybook.pdf" />
    <import file="../../../docbook-support/support.xml" />

    <target name="all.doc" depends="clean">
        <antcall target="lang.all">
            <param name="lang" value="en"/>
        </antcall>
    </target>

</project>

The idea was for this file to delegate most of the work to a support.xml file maintained by the docbook-support project. Developers were supposed to check out the docbook-support project alongside their own project in order to reference this file together with the associated libraries and XSL stylesheets. However what usually happened was that the contents of the docbook-support project were copied into each project's SVN tree. This meant that projects ended up having to maintain their own DocBook build systems and any changes made to the docbook-support project would have to be manually synchronised with their own copy.

With the new Maven2 based system this is no longer an issue as Maven takes care of downloading dependencies automatically. As a result all of the build environment can now be centrally maintained by the Content Team as a set of Maven plugins. You are free to continue using Ant if you prefer but since you won't be using the Maven plugins you will have to maintain any DocBook libraries, XSL stylesheets and CSS files copied or referenced from the docbook-support project yourself.

To perform the build using Ant simply enter the ant command from the directory containing the build.xml file. After it is finished, you should have three output documents in the following places:

The build/en/html directory contains the HTML version of the document. Each chapter is broken into a separate HTML file and they are linked together by an index.html file.
The build/en/html_single directory contains a single index.html file which holds the entire document.
The build/en/pdf directory contains the PDF version of the document.

Note

The HTML output created by Ant is not XHTML. If you wish to gaurantee the separation of content and style then Maven2 should be used instead to produce strict XHTML.

If you wish to migrate from Ant to Maven then all you need to do is copy the docbook-support/docs/guide/pom.xml file to your own DocBook subdirectory (alongside the build.xml file) and then follow the instructions in the previous section. You can then delete the build.xml file as it's not longer needed.