3.2 Customizing your documentation file layout

Unless you absolutely want to change the default settings for building your documentation, you only need to put a single property into the project.properties file.

Figure 3.2. Minimum project.properties file

dbf.basedir = <path to your DocBook Framework installation>

The following additional settings can be changed inside the properties file. Except paper type (see below), these settings normally do not need to be changed:

Table 3.1. DocBook Framework properties

property namedefault valueproperty function
paper.typeLetterPaper output size for PDF docs
src.dir${basedir}/srcdocbook and related sources dir
style.src.dir${src.dir}/stylescustom styles directory
docbook.src.dir${src.dir}/docbookdocbook files directory
images.src.dir${src.dir}/imagesimages location
css.src.dir${src.dir}/csscss files location
target.dir${basedir}/targetoutput directory
tmp.dir${target.dir}/tmptemporary files location

If you do not want to use an absolute location for the dbf.basedir property (e.g. because you want to check the documentation into a version control system and do not want to update the file all the time depending on who checks this file out where), you can put the DocBook Framework in a subdirectory of your documentation.

If you use Subversion, you can even use the svn:externals setting to do this automatically:

Add the following line to the svn:externals property of your documentation root

docbook http://svn.apache.org/repos/asf/velocity/docbook/trunk

and use the following dbf.basedir setting[2]:

dbf.basedir = ${basedir}/docbook

To render your documentation files, you should write a simple ant build file which calls the framework using the docbook.dir and docbook.file properties. If your docbook file is located in src/docbook/manual/ToolManual.xml, your ant build file looks like this:

Figure 3.3. Sample ant build file for rendering documentation

<project name="dbf-docbook" default="all" basedir=".">

  <property file="project.properties"/>

  <target name="all" description="Build documentation">
    <ant antfile="${dbf.basedir}/build-docbook.xml" target="all">
      <property name="docbook.dir" value="manual"/>
      <property name="docbook.file" value="ToolManual"/>


The resulting documentation file will be located in subdirectories of the target/manualdirectory.

[2] This also ensures that everytime you check out your documentation, you will get the lastest version of the DocBook Framework.