3.2 Customizing your documentation file layout

3.2 Customizing your documentation file layout
Prev	3. Using the Framework	Next

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 name	default value	property function
`paper.type`	`Letter`	Paper output size for PDF docs
`src.dir`	`${basedir}/src`	docbook and related sources dir
`style.src.dir`	`${src.dir}/styles`	custom styles directory
`docbook.src.dir`	`${src.dir}/docbook`	docbook files directory
`images.src.dir`	`${src.dir}/images`	images location
`css.src.dir`	`${src.dir}/css`	css files location
`target.dir`	`${basedir}/target`	output directory
`tmp.dir`	`${target.dir}/tmp`	temporary 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"/>
    </ant>
  </target>

</project>

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.