How to use the JBoss DocBook system

Before you can start to build DocBook documents you first need to install and configure Maven2. At the time of writing Maven 2.0.8 is the latest released version that has been tested and found to work correctly. System requirements and download instructions can be found here.

In order for Maven to reference the JBoss public maven repository you will need to create a ~/.m2/settings.xml file with the following contents:

<settings>
  <profiles>
    <profile>
      <id>jboss.repository</id>
      <activation>
        <property>          
          <name>!jboss.repository.off</name>
        </property>
      </activation>
      <repositories>
        <repository>          
          <id>snapshots.jboss.org</id>
          <url>http://snapshots.jboss.org/maven2</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>repository.jboss.org</id>
          <url>http://repository.jboss.org/maven2</url>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>repository.jboss.org</id>
          <url>http://repository.jboss.org/maven2</url>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
        <pluginRepository>
          <id>snapshots.jboss.org</id>
          <url>http://snapshots.jboss.org/maven2</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

If you already have a ~/.m2/settings.xml file then you simply need to add the above <profile> element to your <profiles>.

For example the docs directory for the JBoss Messaging project is shown in Figure 2.1, “The JBoss Messaging docs directory”.

Figure 2.1. The JBoss Messaging docs directory

The easiest way to setup a DocBook subdirectory within your project is to copy the docbook-support/docs/guide directory (containing the DocBook source for this guide) and use it as a template.

Now you can write your content in DocBook format. Make sure that the master file of your DocBook (i.e. the file that contains the <book> element) is called master.xml and lives directly under the en directory (see Figure 2.1, “The JBoss Messaging docs directory”). You can either put the entire content in master.xml or divide up the chapters and place them in the modules/ directory. If you do the latter, you should reference the chapter files from the master.xml file via entity references. Please see the docbook-support/docs/guide/en/master.xml file to see how this is done.

<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:

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.