Each top-level JBoss project (projectname/) in the public CVS stores its documentations in the projectname/docs directory. The projectname/docs directory can contain any number of subdirectories for API references, sample code, user guide etc. But each DocBook should be placed in its own directory directly under projectname/docs. For example, the user's guide DocBook for a project could be placed in projectname/docs/userguide. The easiest way to setup this DocBook directory is to copy the docbook-support/docs/guide directory to your target project and use it as a template. The userguide DocBook structure for the JBoss AOP project is shown in Figure 2.1, “The user guide DocBook in the AOP project ”.

Figure 2.1. The user guide DocBook in the AOP project

Inside the DocBook directory, there are typically several sub-directories, each corresponding to a specific lanuguage version of the document. The English version resides in the en/ sub-directory. Inside each language directory, there are typically two sub-directories for contents:

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) in the master.xml file directly under the language directory (see Figure 2.1, “The user guide DocBook in the AOP project ”). 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 reference. Please see the docbook-support/docs/guide/en/master.xml file to see how it is done.

To build the deliverable documents, just run ANT against the build.xml file in the DocBook directory. The build.xml file is really simple and its content is shown below. It delegates most of the tasks to the support.xml file mainatined by the docbook-support project.

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

After the build is finished, you have three output documents for each language edition in the following places: