3.4 Notes

Changing the paper size

The DocBook Framework renders the pages of the PDF output by default in US Letter format (8.5 x 11 inches). This allows printing the resulting PDF in both Letter and A4 format.

If you want to reformat the PDF documentation in A4, you can use the paper.type property when invoking ant or by setting it permanently in the project.properties file.

Figure 3.4. Rendering documentation in A4 format

ant -Dpaper.type=A4 will render the documentation in A4.

Referencing images

While the docbook files are located in their respective subdirectories below src/docbook, your image files should be put into the src/images directory.

When writing documentation, images are referenced as images/<your image file name here> because this is where they will end up when rendering your documentation.

[Warning]Warning

If your DocBook writing tool does not allow you to specify image locations, it might not be able to locate the images from src/images and just display a broken image symbol. If this concerns you, you can create a symbolic link inside the source directory where your DocBook files reside to the src/images directory.

Adding a new DocBook file to your documentation build

Create a new subdirectory inside src/docbook. This is where your new DocBook document will reside.

In your documentation ant build file, you must then add a reference to render your new document. To add a DocBook document called NewGuide.xml which has been located in the guide subdirectory, see the following example:

Figure 3.5. Adding a new DocBook document

<ant antfile="build-docbook.xml" target="all">
  <property name="docbook.dir" value="guide"/> 1
  <property name="docbook.file" value="NewGuide"/> 2
</ant>
1

The new DocBook file is located in src/docbook/guide.

2

This is the name of the main docbook file WITHOUT the ending. The framework will add .xml when opening the DocBook file automatically.


When you add a new document to the framework, you should make sure that it references DocBook DTD files which can be resolved locally. Included are the DTD files for DocBook 4.4, so your document declaration should be

Figure 3.6. Recommended DTD for DocBook documents.

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

If you use a different doctype definition, the DocBook Framework will still render your documents, but it will have to connect to the Internet to retrieve the definition files every time you run the build process.