<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>3.2&nbsp;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.&nbsp;Using the Framework"><link rel="prev" href="ch03.html" title="3.&nbsp;Using the Framework"><link rel="next" href="ch03s03.html" title="3.3&nbsp;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&nbsp;Customizing your documentation file layout</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch03.html">Prev</a>&nbsp;</td><th width="60%" align="center">3.&nbsp;Using the Framework</th><td width="20%" align="right">&nbsp;<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&nbsp;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&nbsp;3.2.&nbsp;Minimum project.properties file</b></p><div class="figure-contents"><pre class="programlisting">dbf.basedir = &lt;path to your DocBook Framework installation&gt;</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&nbsp;3.1.&nbsp;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&nbsp;3.3.&nbsp;Sample ant build file for rendering documentation</b></p><div class="figure-contents"><pre class="programlisting">&lt;project name="dbf-docbook" default="all" basedir="."&gt;

  &lt;property file="project.properties"/&gt;

  &lt;target name="all" description="Build documentation"&gt;
    &lt;ant antfile="${dbf.basedir}/build-docbook.xml" target="all"&gt;
      &lt;property name="docbook.dir" value="manual"/&gt;
      &lt;property name="docbook.file" value="ToolManual"/&gt;
    &lt;/ant&gt;
  &lt;/target&gt;

&lt;/project&gt;</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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch03.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch03s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.&nbsp;Using the Framework&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;3.3&nbsp;Writing your documentation</td></tr></table></div></body></html>