| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>DocBook Framework (DBF)</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.70.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="d0e2"></a>DocBook Framework (DBF)</h1></div><div><div class="authorgroup"><h3 class="corpauthor">The Apache Velocity Developers</h3></div></div><div><div class="mediaobject"><img src="images/logo.png"></div></div><div><p class="releaseinfo">V 1.0</p></div><div><p class="copyright">Copyright © 2006-2007 The Apache Software Foundation</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#chapter-preface">1. Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#section-about-this-project">1.1. About this Project</a></span></dt><dt><span class="section"><a href="#section-license">1.2. License Information</a></span></dt><dt><span class="section"><a href="#section-author-information">1.3. Author Information</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chapter-introduction">2. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#section-why-another-framework">2.1. Why another framework for rendering docbook?</a></span></dt><dt><span class="section"><a href="#section-what-you-need">2.2. What you need</a></span></dt><dt><span class="section"><a href="#section-caveat-emptor">2.3. Caveat Emptor!</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chapter-using-the-framework">3. Using the Framework</a></span></dt><dd><dl><dt><span class="section"><a href="#section-how-to-set-up">3.1. How to set up your documentation files</a></span></dt><dt><span class="section"><a href="#section-configuring-your-documentation">3.2. Customizing your documentation file layout</a></span></dt><dt><span class="section"><a href="#section-writing-your-documentation">3.3. Writing your documentation</a></span></dt><dt><span class="section"><a href="#section-notes">3.4. Notes</a></span></dt><dd><dl><dt><span class="section"><a href="#section-changing-the-paper-size">Changing the paper size</a></span></dt><dt><span class="section"><a href="#section-referencing-images">Referencing images</a></span></dt><dt><span class="section"><a href="#section-adding-a-new-docbook-file">Adding a new DocBook file to your documentation build</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#section-how-it-works">4. Developer information</a></span></dt><dd><dl><dt><span class="section"><a href="#section-ant-files">4.1. ant files</a></span></dt><dt><span class="section"><a href="#section-docbook-reference-files">4.2. DocBook reference files</a></span></dt><dt><span class="section"><a href="#section-xml-resolver">4.3. XML Resolver</a></span></dt><dt><span class="section"><a href="#section-docbook-source-files">4.4. Docbook Source files</a></span></dt><dt><span class="section"><a href="#section-stylesheets-and-driver-files">4.5. Stylesheets and Driver files</a></span></dt><dt><span class="section"><a href="#section-stylesheet-customizations">4.6. StyleSheet customizations</a></span></dt><dt><span class="section"><a href="#section-pdf-stylesheet">4.7. PDF StyleSheet information</a></span></dt><dt><span class="section"><a href="#section-titlepages">4.8. Titlepages</a></span></dt></dl></dd><dt><span class="chapter"><a href="#section-acknowledgements">5. Acknowledgements</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-preface"></a>1. Preface</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-about-this-project"></a>1.1 About this Project</h2></div></div></div><p>This project started out as a framework to render documentation |
| for the Apache Velocity project ( |
| <code class="uri">http://velocity.apache.org/</code>) and ended somehow up to be a |
| generic framework to render DocBook documents using Java and driven by |
| Apache ant.</p><p>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.</p><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-license"></a>1.2 License Information</h2></div></div></div><p>Copyright © 2006-2007 The Apache Software Foundation.</p><p>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 |
| <code class="uri">http://www.apache.org/licenses/LICENSE-2.0</code></p><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-author-information"></a>1.3 Author Information</h2></div></div></div><p>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 <code class="email"><<a href="mailto:dev@velocity.apache.org">dev@velocity.apache.org</a>></code></p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-introduction"></a>2. Introduction</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-why-another-framework"></a>2.1 Why another framework for rendering docbook?</h2></div></div></div><p>The Velocity project used a simple HTML based format called |
| <em class="firstterm">XDOC</em> for its documentation for a very long time. |
| However, <em class="firstterm">XDOC</em> is not really popular outside the |
| Apache world<sup>[<a name="d0e69" href="#ftn.d0e69">1</a>]</sup>, 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.</p><p>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.</p><p>What we wanted to have, was a framework, that...</p><div class="itemizedlist"><ul type="disc"><li><p>...renders multiple documents into multiple formats with an |
| uniform look without having to copy a large number of stylesheets, |
| images and other supporting files around.</p></li><li><p>...separates the render framework and the actual documentation |
| to render. It should be sufficient to install the framework only |
| once and then reference it.</p></li><li><p>...uses the standard DocBook XML and XSL zip files available |
| for download. Many of the open source DocBook frameworks use heavily |
| hacked versions and we want to be able to keep up with releases |
| without having to patch the released files every time.</p></li><li><p>...uses current versions of the DocBook reference files, the |
| libraries and supporting tools.</p></li><li><p>...render all formats without connecting to the Internet. |
| Using the Apache XML resolver, it should be possible to use the |
| framework completely standalone. See |
| <code class="uri">http://xml.apache.org/commons/components/resolver/resolver-article.html</code> |
| for an explanation.</p></li><li><p>...has some documentation so you understand what happens when |
| a format gets rendered and how.</p></li><li><p>...that can be customized easily (if you consider customizing |
| complex XSL style sheets 'easy').</p></li><li><p>...that is platform independent and uses 100% pure Java. No |
| external programs should be needed or called.</p></li><li><p>...that is driven by Apache ant and could be easily embedded |
| into larger builds.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-what-you-need"></a>2.2 What you need</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>A Java Runtime. All testing has been done using the Sun JSDK |
| 1.5.0</p></li><li><p>Apache Ant version 1.6 or better. The build script uses the |
| macrodef task which was introduced in ant 1.6. Any later version |
| should work, too. Get it from |
| <code class="uri">http://ant.apache.org/</code></p></li><li><p>The Sun JAI libraries. Please see the |
| <code class="literal">README.FIRST</code> file on how to get and install |
| these.</p></li></ul></div><p>Everything else needed should be included in this package.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-caveat-emptor"></a>2.3 Caveat Emptor!</h2></div></div></div><p>This framework has been written for the Velocity documentation and |
| we also tried to do a reasonably good job in documentating it.</p><p>In any case, the last and final word is in the Subversion |
| repository for the DocBook Framework at<code class="uri"> |
| http://svn.apache.org/repos/asf/velocity/docbook/trunk/</code></p><p>The reference on how to setup and build documentation is the |
| Velocity documentation at<code class="uri"> |
| http://svn.apache.org/repos/asf/velocity/docs/</code> and also the |
| DocBook Framework documentation itself which is located in the |
| <code class="literal">docs/</code> subfolder of the distribution. If in doubt, |
| please check there on how the framework is used.</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.d0e69" href="#d0e69">1</a>] </sup>And not even in the Apache world...</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-using-the-framework"></a>3. Using the Framework</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-how-to-set-up"></a>3.1 How to set up your documentation files</h2></div></div></div><p>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.</p><div class="figure"><a name="figure-recommended-layout"></a><p class="title"><b>Figure 3.1. Recommended layout for a documentation project</b></p><div class="figure-contents"><pre class="programlisting"><root> |
| | |
| +---- build.xml <a name="co-build-xml" href="#ca-build-xml"><img src="images/callouts/1.gif" alt="1" border="0"></a> |
| +---- project.properties <a name="co-project-properties" href="#ca-project-properties"><img src="images/callouts/2.gif" alt="2" border="0"></a> |
| | |
| +-- src |
| | |
| +-- docbook <a name="co-docbook-sources" href="#ca-docbook-sources"><img src="images/callouts/3.gif" alt="3" border="0"></a> |
| | |
| +-- styles |
| | | |
| | +-- pdf <a name="co-styles-pdf" href="#ca-styles-pdf"><img src="images/callouts/4.gif" alt="4" border="0"></a> |
| | | |
| | +-- html <a name="co-styles-html" href="#ca-styles-html"><img src="images/callouts/5.gif" alt="5" border="0"></a> |
| | |
| +-- css |
| | | |
| | +-- html <a name="co-css-html" href="#ca-css-html"><img src="images/callouts/6.gif" alt="6" border="0"></a> |
| | |
| +-- images <a name="co-src-images" href="#ca-src-images"><img src="images/callouts/7.gif" alt="7" border="0"></a></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a name="ca-build-xml"></a><a href="#co-build-xml"><img src="images/callouts/1.gif" alt="1" border="0"></a> </td><td valign="top" align="left"><p>ant build file</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-project-properties"></a><a href="#co-project-properties"><img src="images/callouts/2.gif" alt="2" border="0"></a> </td><td valign="top" align="left"><p>custom settings for your build</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-docbook-sources"></a><a href="#co-docbook-sources"><img src="images/callouts/3.gif" alt="3" border="0"></a> </td><td valign="top" align="left"><p>Docbook sources</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-styles-pdf"></a><a href="#co-styles-pdf"><img src="images/callouts/4.gif" alt="4" border="0"></a> </td><td valign="top" align="left"><p>Custom styles for PDF</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-styles-html"></a><a href="#co-styles-html"><img src="images/callouts/5.gif" alt="5" border="0"></a> </td><td valign="top" align="left"><p>Custom styles for HTML</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-css-html"></a><a href="#co-css-html"><img src="images/callouts/6.gif" alt="6" border="0"></a> </td><td valign="top" align="left"><p>CSS files for HTML</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-src-images"></a><a href="#co-src-images"><img src="images/callouts/7.gif" alt="7" border="0"></a> </td><td valign="top" align="left"><p>Image files for PDF/HTML</p></td></tr></table></div></div></div><br class="figure-break"><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-configuring-your-documentation"></a>3.2 Customizing your documentation file layout</h2></div></div></div><p>Unless you absolutely want to change the default settings for |
| building your documentation, you only need to put a single property into |
| the <em class="firstterm">project.properties</em> file.</p><div class="figure"><a name="figure-minimum-project-properties"></a><p class="title"><b>Figure 3.2. Minimum project.properties file</b></p><div class="figure-contents"><pre class="programlisting">dbf.basedir = <path to your DocBook Framework installation></pre></div></div><br class="figure-break"><p>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:</p><div class="table"><a name="table-docbook-framework-properties"></a><p class="title"><b>Table 3.1. DocBook Framework properties</b></p><div class="table-contents"><table summary="DocBook Framework properties" border="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">property name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">default value</th><th style="border-bottom: 0.5pt solid ; ">property function</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">paper.type</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">Letter</code></td><td style="border-bottom: 0.5pt solid ; ">Paper output size for PDF docs</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">src.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${basedir}/src</code></td><td style="border-bottom: 0.5pt solid ; ">docbook and related sources dir</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">style.src.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${src.dir}/styles</code></td><td style="border-bottom: 0.5pt solid ; ">custom styles directory</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">docbook.src.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${src.dir}/docbook</code></td><td style="border-bottom: 0.5pt solid ; ">docbook files directory</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">images.src.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${src.dir}/images</code></td><td style="border-bottom: 0.5pt solid ; ">images location</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">css.src.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${src.dir}/css</code></td><td style="border-bottom: 0.5pt solid ; ">css files location</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">target.dir</code></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><code class="literal">${basedir}/target</code></td><td style="border-bottom: 0.5pt solid ; ">output directory</td></tr><tr><td style="border-right: 0.5pt solid ; "><code class="literal">tmp.dir</code></td><td style="border-right: 0.5pt solid ; "><code class="literal">${target.dir}/tmp</code></td><td style="">temporary files location</td></tr></tbody></table></div></div><br class="table-break"><p>If you do not want to use an absolute location for the |
| <code class="literal">dbf.basedir</code> 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.</p><p>If you use Subversion, you can even use the |
| <code class="literal">svn:externals</code> setting to do this |
| automatically:</p><p>Add the following line to the <code class="literal">svn:externals</code> |
| property of your documentation root</p><pre class="programlisting">docbook http://svn.apache.org/repos/asf/velocity/docbook/trunk</pre><p>and use the following <code class="literal">dbf.basedir</code> |
| setting<sup>[<a name="d0e319" href="#ftn.d0e319">2</a>]</sup>:</p><pre class="programlisting">dbf.basedir = ${basedir}/docbook</pre><p>To render your documentation files, you should write a simple ant |
| build file which calls the framework using the |
| <code class="literal">docbook.dir</code> and <code class="literal">docbook.file |
| properties</code>. If your docbook file is located in |
| <code class="literal">src/docbook/manual/ToolManual.xml</code>, your ant build |
| file looks like this:</p><div class="figure"><a name="figure-sample-ant-build-file"></a><p class="title"><b>Figure 3.3. Sample ant build file for rendering documentation</b></p><div class="figure-contents"><pre class="programlisting"><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></pre></div></div><br class="figure-break"><p>The resulting documentation file will be located in subdirectories |
| of the <code class="literal">target/manual</code>directory.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-writing-your-documentation"></a>3.3 Writing your documentation</h2></div></div></div><p>Your DocBook source files normally reside in subdirectories below |
| the<code class="literal">src/docbook</code>folder. Each document has its own |
| folder that is referenced through the <code class="literal">docbook.dir</code> |
| property as shown above.</p><p>In the example above, running <code class="literal">ant all</code> (or just |
| <code class="literal">ant</code>) will build all the documentation formats for the |
| ToolManual DocBook file.</p><div class="table"><a name="default-formats-built-in"></a><p class="title"><b>Table 3.2. Default formats built by the DocBook Framework</b></p><div class="table-contents"><table summary="Default formats built by the DocBook Framework" border="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col><col></colgroup><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">pdf</td><td style="border-bottom: 0.5pt solid ; ">Adobe PDF format</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">html</td><td style="border-bottom: 0.5pt solid ; ">Multiple HTML files, one file for each section</td></tr><tr><td style="border-right: 0.5pt solid ; ">htmlsingle</td><td style="">One big HTML file</td></tr></tbody></table></div></div><br class="table-break"><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-notes"></a>3.4 Notes</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section-changing-the-paper-size"></a>Changing the paper size</h3></div></div></div><p>The DocBook Framework renders the pages of the PDF output by |
| default in <span class="emphasis"><em>US Letter</em></span> format (8.5 x 11 inches). |
| This allows printing the resulting PDF in both Letter and A4 |
| format.</p><p>If you want to reformat the PDF documentation in A4, you can use |
| the <code class="literal">paper.type</code> property when invoking ant or by |
| setting it permanently in the <code class="literal">project.properties</code> |
| file.</p><div class="figure"><a name="figure-rendering-in-a4"></a><p class="title"><b>Figure 3.4. Rendering documentation in A4 format</b></p><div class="figure-contents"><pre class="programlisting">ant -Dpaper.type=A4 will render the documentation in A4.</pre></div></div><br class="figure-break"></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section-referencing-images"></a>Referencing images</h3></div></div></div><p>While the docbook files are located in their respective |
| subdirectories below src/docbook, your image files should be put into |
| the <code class="literal">src/images</code> directory.</p><p>When writing documentation, images are referenced as |
| <code class="literal">images/<your image file name here></code> because |
| this is where they will end up when rendering your |
| documentation.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.gif"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If your DocBook writing tool does not allow you to specify |
| image locations, it might not be able to locate the images from |
| <code class="literal">src/images</code> 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 |
| <code class="literal">src/images</code> directory.</p></td></tr></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section-adding-a-new-docbook-file"></a>Adding a new DocBook file to your documentation build</h3></div></div></div><p>Create a new subdirectory inside <code class="literal">src/docbook</code>. |
| This is where your new DocBook document will reside.</p><p>In your documentation ant build file, you must then add a |
| reference to render your new document. To add a DocBook document |
| called <span class="emphasis"><em>NewGuide.xml</em></span> which has been located in the |
| <code class="literal">guide</code> subdirectory, see the following |
| example:</p><div class="figure"><a name="figure-adding-new-document"></a><p class="title"><b>Figure 3.5. Adding a new DocBook document</b></p><div class="figure-contents"><pre class="programlisting"><ant antfile="build-docbook.xml" target="all"> |
| <property name="docbook.dir" value="guide"/> <a name="co-docbook-dir" href="#ca-docbook-dir"><img src="images/callouts/1.gif" alt="1" border="0"></a> |
| <property name="docbook.file" value="NewGuide"/> <a name="co-docbook-file" href="#ca-docbook-file"><img src="images/callouts/2.gif" alt="2" border="0"></a> |
| </ant></pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><a name="ca-docbook-dir"></a><a href="#co-docbook-dir"><img src="images/callouts/1.gif" alt="1" border="0"></a> </td><td valign="top" align="left"><p>The new DocBook file is located in |
| <code class="literal">src/docbook/guide</code>.</p></td></tr><tr><td width="5%" valign="top" align="left"><a name="ca-docbook-file"></a><a href="#co-docbook-file"><img src="images/callouts/2.gif" alt="2" border="0"></a> </td><td valign="top" align="left"><p>This is the name of the main docbook file |
| <span class="emphasis"><em>WITHOUT</em></span> the ending. The framework will add |
| <code class="literal">.xml</code> when opening the DocBook file |
| automatically.</p></td></tr></table></div></div></div><br class="figure-break"><p>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</p><div class="figure"><a name="figure-recommended-dtd"></a><p class="title"><b>Figure 3.6. Recommended DTD for DocBook documents.</b></p><div class="figure-contents"><pre class="programlisting"><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"></pre></div></div><br class="figure-break"><p>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.</p></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.d0e319" href="#d0e319">2</a>] </sup>This also ensures that everytime you check out your |
| documentation, you will get the lastest version of the DocBook |
| Framework.</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="section-how-it-works"></a>4. Developer information</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.gif"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>First take a look at the <code class="literal">MANIFEST</code> file in the |
| root directory to get an idea what is in this package and what the |
| various files are supposed to do.</p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-ant-files"></a>4.1 ant files</h2></div></div></div><p>The <code class="literal">build.xml</code> file in your documentation |
| directory contains only the driver targets for rendering the |
| documentation. The actual work is done through targets defined in the |
| <code class="literal">build-docbook.xml</code> ant file in the DocBook |
| Framework.</p><p>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.</p><p><code class="literal">build-docbook.xml</code> contains three main targets: |
| <code class="literal">pdf</code>, <code class="literal">html</code> and |
| <code class="literal">htmlsingle</code>. Each is responsible for rendering a |
| format. If you want to add another format, please style your new target |
| similar to these.</p><p>All default settings are kept in the |
| <code class="literal">docbook.properties</code> 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 <code class="literal">project.properties</code> |
| file.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-docbook-reference-files"></a>4.2 DocBook reference files</h2></div></div></div><p>We use the DocBook XML and XSL distribution archives without any |
| changes to them. The reference files are located in the |
| <code class="literal">src/zip</code> folder and are expanded into the |
| <code class="literal">target/</code> directory before the rendering |
| process.</p><p>The file names must be reflected in the |
| <code class="literal">docbook.xml.version</code> and |
| <code class="literal">docbook.xsl.version</code> properties in the |
| <code class="literal">docbook.properties</code> file. If you want to use e.g. a |
| newer XSL version, you can put it into <code class="literal">src/zip</code> and |
| update the <code class="literal">docbook.properties</code> to reflect this change. |
| Let us know how it works out for you.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-xml-resolver"></a>4.3 XML Resolver</h2></div></div></div><p>The framework uses the Apache XML commons resolver to avoid |
| accessing the Internet for Catalog files. The resolver is configured |
| through the <code class="literal">CatalogManager.properties</code> and |
| <code class="literal">xml-catalog.xml</code> files in the |
| <code class="literal">src/resolver</code> directory of the distribution.</p><p>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.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-docbook-source-files"></a>4.4 Docbook Source files</h2></div></div></div><p>The sources for each DocBook document to render should be in |
| subdirectories of <code class="literal">src/docbook</code>. Each document has its |
| own subdirectory and gets rendered separately. Adding a new document is |
| described in the <span class="emphasis"><em>Adding a new DocBook file to your |
| Documentation build</em></span> note above.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-stylesheets-and-driver-files"></a>4.5 Stylesheets and Driver files</h2></div></div></div><p>For each of the formats used by the framework, a stylesheet driver |
| file exists in the DocBook Framework in <code class="literal">src/styles</code>. |
| These files are <code class="literal">pdf.xsl</code>, <code class="literal">html.xsl</code> |
| and <code class="literal">htmlsingle.xsl</code>.</p><p>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 |
| <span class="emphasis"><em>html</em></span> and <span class="emphasis"><em>htmlsingle</em></span> are very |
| similar and it makes no sense to maintain two sets of stylesheet |
| customizations that are virtually identical.</p><p>Before usage, these files are copied to |
| <code class="literal">target/tmp</code> using an ant filter set. This allows you |
| to use the following replacements in the driver files:</p><div class="table"><a name="ant-filter-tokens"></a><p class="title"><b>Table 4.1. ant filter tokens in the stylesheet customization files</b></p><div class="table-contents"><table summary="ant filter tokens in the stylesheet customization files" border="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col><col><col></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Filter token</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">Default Value</th><th style="border-bottom: 0.5pt solid ; ">Token function</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">@file.prefix@</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; "><table width="100%" border="0" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col></colgroup><tbody><tr><td style="border-bottom: 0.5pt solid ; ">file:// (Unix)</td></tr><tr><td style="">file:/// (Windows)</td></tr></tbody></table></td><td style="border-bottom: 0.5pt solid ; ">Prefix for loading a file through the XSL |
| processor.</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">@docbook.xml@</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">(computed at runtime)</td><td style="border-bottom: 0.5pt solid ; ">Location of the DocBook XML files</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">@docbook.xsl@</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">(computed at runtime)</td><td style="border-bottom: 0.5pt solid ; ">Location of the DocBook XSL style sheets</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">@src.dir@</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">${basedir}/src</td><td style="border-bottom: 0.5pt solid ; ">Location of the source files (DocBook, Images |
| etc.)</td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">@tmp.dir@</td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; ">${basedir}/target/tmp</td><td style="border-bottom: 0.5pt solid ; ">Directory for temporary (scratch) files</td></tr><tr><td style="border-right: 0.5pt solid ; ">@<type>.target.dir@ (type is pdf for PDF, html for |
| multi-page HTML and htmlsingle for single-page HTML)</td><td style="border-right: 0.5pt solid ; ">(computed at runtime)</td><td style="">Points to the target directory into which the document is |
| rendered</td></tr></tbody></table></div></div><br class="table-break"><p>Please refer to the provided driver files in |
| <code class="literal">src/styles</code> in the DocBook Framework on how to use the |
| filter set.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-stylesheet-customizations"></a>4.6 StyleSheet customizations</h2></div></div></div><p>You can customize the stylesheets used to render the documentation |
| by adding style files to your project.</p><p>The <span class="emphasis"><em>html</em></span> and <span class="emphasis"><em>htmlsingle</em></span> |
| render process uses the same set of customizations, so there are only |
| two possible locations, one for PDF and one for HTML.</p><p>The files are located in your project under |
| <code class="literal">src/styles/pdf</code> and <code class="literal">src/styles/html</code> |
| respectively. The DocBook Framework only loads a file named |
| <code class="literal">custom.xsl</code> file from the directory, which in turn can |
| load additional files.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-pdf-stylesheet"></a>4.7 PDF StyleSheet information</h2></div></div></div><p>In the footer, the <code class="literal"><releaseinfo></code> and |
| <code class="literal"><productname></code> elements of the DocBook document |
| are displayed. Each document should have these fields defined.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-titlepages"></a>4.8 Titlepages</h2></div></div></div><p>Similar to the style sheet customizations, the DocBook Framework |
| can use custom title pages when rendering PDF and HTML output.</p><p>The title page format files are also be kept in the |
| <code class="literal">src/styles/html</code> and <code class="literal">src/styles/pdf</code> |
| sub-directories of your documentation project. If no custom page is |
| given, a default title page is used.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="section-acknowledgements"></a>5. Acknowledgements</h2></div></div></div><p>DocBook is a fairly complex format and using and customizing the XSL |
| style sheets available is not really straightforward. So by googling left |
| and right and looking at other DocBook rendering frameworks that are in |
| the open source, we tried to model similarities and sometimes just copied |
| some of the ideas.</p><p>This DocBook Framework is literally standing on the shoulders of |
| other projects, in particular:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>The DocBook Format</em></span> by Norman Walsh; (C) |
| 1999-2006 by Norman Walsh, OASIS and O'Reilly, especially all the |
| documentation that is available from |
| <code class="uri">http://www.docbook.org/</code></p></li><li><p><span class="emphasis"><em>The DocBook FAQ</em></span> maintained by Dave Pawson |
| and available from <code class="uri">http://www.dpawson.co.uk/docbook/</code>. We |
| wouldn't have survived without it.</p></li><li><p><span class="emphasis"><em>DocBook XSL: The Complete Guide</em></span> by Bob |
| Stayton. This is an invaluable reference to the DocBook style sheets. |
| Find it online at <code class="uri">http://sagehill.net/</code> or buy the |
| E-book.</p></li><li><p><span class="emphasis"><em>The DocBook Project</em></span> located at |
| <code class="uri">http://docbook.sourceforge.net/</code>. They maintain the XSL |
| style sheets used to transform DocBook into other formats and also |
| link to the docbook mailing list archives.</p></li><li><p><span class="emphasis"><em>The Apache XML commons resolver</em></span> available |
| from |
| <code class="uri">http://xml.apache.org/commons/components/resolver/</code></p></li><li><p><span class="emphasis"><em>The XMLmind XML Editor</em></span> from XMLMind, |
| available through <code class="uri">http://www.xmlmind.com/xmleditor/</code> This |
| cross-platform, pure Java editor not only runs well on Linux, Windows |
| and MacOS but also offers DocBook WYSIWYG support and has a free |
| version! And if you pay for it, you get the source code for it |
| too.</p></li></ul></div><p>Ideas on how to render elements, to arrange things and how to do |
| more obscure things like title pages or use CSS to render HTML, we've |
| taken (sometimes literally by cut and paste) from the following |
| projects:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>The Spring Framework documentation</em></span>. It |
| hooked us on the idea that Velocity should have DocBook documentation, |
| too. Their DocBook framework is really nice, however it proved to be |
| 'not exactly what we were looking for' (see above). Spring is an |
| example on how good documentation makes all the difference between a |
| successful and popular project and 'the others'. Thanks a lot, Spring |
| guys! Download Spring Framework from |
| <code class="uri">http://www.springframework.org/</code>.</p></li><li><p><span class="emphasis"><em>The "ant and docbook" styler suite</em></span> by Dawid |
| Weiss, available from |
| <code class="uri">http://www.cs.put.poznan.pl/dweiss/xml/projects/ant-docbook-styler/index.xml</code> |
| . We stole his CSS style sheet almost verbatim. Thanks a lot, |
| Dawid!</p></li><li><p><span class="emphasis"><em>The Maven sdocbook plugin</em></span> by Siegfried |
| Goeschl, Per Olesen and Carlos Sanchez, available at the SourceForge |
| Maven plugin page at |
| <code class="uri">http://maven-plugins.sourceforge.net/maven-sdocbook-plugin/</code></p></li></ul></div></div></div></body></html> |
