| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>3.2 Customizing your documentation file layout</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.70.0"><link rel="start" href="index.html" title="DocBook Framework (DBF)"><link rel="up" href="ch03.html" title="3. Using the Framework"><link rel="prev" href="ch03.html" title="3. Using the Framework"><link rel="next" href="ch03s03.html" title="3.3 Writing your documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.2 Customizing your documentation file layout</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch03.html">Prev</a> </td><th width="60%" align="center">3. Using the Framework</th><td width="20%" align="right"> <a accesskey="n" href="ch03s03.html">Next</a></td></tr></table><hr></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 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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch03s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Using the Framework </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.3 Writing your documentation</td></tr></table></div></body></html> |
