DocBook Framework (DBF)

This project started out as a framework to render documentation for the Apache Velocity project ( http://velocity.apache.org/) and ended somehow up to be a generic framework to render DocBook documents using Java and driven by Apache ant.

While DocBook format seems to be ubiquitous these days, to our surprise there were not many generic frameworks around that could render all kinds of formats, are platform independent, do not require lots of infrastructure installed and are easily customizable.

Projects either use heavily customized and hacked style sheets or a mix of Java and other applications. Adjusting such a rendering framework to the needs of the Apache Velocity project was not easy, so at some point, we decided to redo this (almost) from scratch.

Copyright © 2006-2007 The Apache Software Foundation.

Licensed under the Apache License, Version 2.0 (the "License") you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This framework and documentation was written by the Apache Velocity Developers. If you have questions, found a bug or have enhancements, please contact us through the Apache Velocity Development Mailing list at <dev@velocity.apache.org>

The Velocity project used a simple HTML based format called XDOC for its documentation for a very long time. However, XDOC is not really popular outside the Apache world^[1], it renders somehow into HTML but no other formats (unless you consider a set of alpha and beta-level plugins for maven-1 and maven-2) and tool support for this format is not really there.

When an XML based format for documentation is considered, DocBook seems to be a natural choice. So we decided to take a stab at rendering the existing Velocity Docs that are end-user specific (Users Guide, Developers Guide, Reference and the likes) through DocBook.

What we wanted to have, was a framework, that...

Everything else needed should be included in this package.

This framework has been written for the Velocity documentation and we also tried to do a reasonably good job in documentating it.

In any case, the last and final word is in the Subversion repository for the DocBook Framework at http://svn.apache.org/repos/asf/velocity/docbook/trunk/

The reference on how to setup and build documentation is the Velocity documentation at http://svn.apache.org/repos/asf/velocity/docs/ and also the DocBook Framework documentation itself which is located in the docs/ subfolder of the distribution. If in doubt, please check there on how the framework is used.

Writing documentation is not just writing text. Often, an author wants to add images, customize the layout of the pages or use specific style information to format documentation in e.g. HTML format. All the required files must be found by the DocBook Framework for creating output files.

Figure 3.1. Recommended layout for a documentation project

<root>
  |
  +---- build.xml 
  +---- project.properties 
  |
  +-- src
       |
       +-- docbook 
       |
       +-- styles
       |     |
       |     +-- pdf 
       |     |
       |     +-- html 
       |
       +-- css
       |    |
       |    +-- html 
       |
       +-- images 

	ant build file
	custom settings for your build
	Docbook sources
	Custom styles for PDF
	Custom styles for HTML
	CSS files for HTML
	Image files for PDF/HTML

It is possible to customize this file layout further to adjust it to existing documentation. If you start a new documentation project, then we recommend that you start with this layout until you are familiar on how the DocBook Framework behaves.

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.

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:

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:

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

Your DocBook source files normally reside in subdirectories below thesrc/docbookfolder. Each document has its own folder that is referenced through the docbook.dir property as shown above.

In the example above, running ant all (or just ant) will build all the documentation formats for the ToolManual DocBook file.

Both of the HTML format directories will also contain a Zip file suitable for distribution, which contains all HTML files, images and optional CSS files.

The build.xml file in your documentation directory contains only the driver targets for rendering the documentation. The actual work is done through targets defined in the build-docbook.xml ant file in the DocBook Framework.

This file normally should not be changed! If you have to, please let us know, so we can incorporate your changes and/or bug fixes into the main distribution.

build-docbook.xml contains three main targets: pdf, html and htmlsingle. Each is responsible for rendering a format. If you want to add another format, please style your new target similar to these.

All default settings are kept in the docbook.properties file in the root directory. There should be no need to change these properties, they can be customized in your project directory by using a project.properties file.

We use the DocBook XML and XSL distribution archives without any changes to them. The reference files are located in the src/zip folder and are expanded into the target/ directory before the rendering process.

The file names must be reflected in the docbook.xml.version and docbook.xsl.version properties in the docbook.properties file. If you want to use e.g. a newer XSL version, you can put it into src/zip and update the docbook.properties to reflect this change. Let us know how it works out for you.

The framework uses the Apache XML commons resolver to avoid accessing the Internet for Catalog files. The resolver is configured through the CatalogManager.properties and xml-catalog.xml files in the src/resolver directory of the distribution.

If you update e.g. the Docbook XML version, you must also update the catalog file to match the new version. Else the rendering process will have no knowledge of your changes and access the Internet to download the required DTD files.

The sources for each DocBook document to render should be in subdirectories of src/docbook. Each document has its own subdirectory and gets rendered separately. Adding a new document is described in the Adding a new DocBook file to your Documentation build note above.

For each of the formats used by the framework, a stylesheet driver file exists in the DocBook Framework in src/styles. These files are pdf.xsl, html.xsl and htmlsingle.xsl.

The driver files are intended to reference the actual style sheet customization and to add some framework specific elements through filtering. This two step process has been chosen because html and htmlsingle are very similar and it makes no sense to maintain two sets of stylesheet customizations that are virtually identical.

Before usage, these files are copied to target/tmp using an ant filter set. This allows you to use the following replacements in the driver files:

Please refer to the provided driver files in src/styles in the DocBook Framework on how to use the filter set.

You can customize the stylesheets used to render the documentation by adding style files to your project.

The html and htmlsingle render process uses the same set of customizations, so there are only two possible locations, one for PDF and one for HTML.

The files are located in your project under src/styles/pdf and src/styles/html respectively. The DocBook Framework only loads a file named custom.xsl file from the directory, which in turn can load additional files.

In the footer, the <releaseinfo> and <productname> elements of the DocBook document are displayed. Each document should have these fields defined.

Similar to the style sheet customizations, the DocBook Framework can use custom title pages when rendering PDF and HTML output.

The title page format files are also be kept in the src/styles/html and src/styles/pdf sub-directories of your documentation project. If no custom page is given, a default title page is used.