| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>3.4 Notes</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="ch03s03.html" title="3.3 Writing your documentation"><link rel="next" href="ch04.html" title="4. Developer information"></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.4 Notes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch03s03.html">Prev</a> </td><th width="60%" align="center">3. Using the Framework</th><td width="20%" align="right"> <a accesskey="n" href="ch04.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-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="ch03s04.html#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="ch03s04.html#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="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch03s03.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="ch04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.3 Writing your documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4. Developer information</td></tr></table></div></body></html> |
