The source files of the documentation are located in <base-dir>/doc/src/docbook. The different parts of the documentation are organized into separate folders and each one of the folders contains one index file and one file for each chapter in that part. The index file joins the chapters, in current part/folder, together and does not really contain any text. The documentation root directory also contains an index.xml file which joins the index files from the different parts together.

Figure 30.1. The organization of documentation files

We have configured docbook to create a new sub-directory for each <chapter> and a new output file for each <sect1> tag. In most cases this gives each page a relatively good size. Not too long and not too short. However, if a chapter contains many small <sect1> sections (for example, Chapter 4, Resources), you end up with many pages with just a few lines of text on each page. This is not so good and can be avoided by adding chunked="0" as an attribute to the <chapter> tag, for example:

<chapter id="resources" chunked="0">

This will stop the chunking of <sect1> sections in this chapter.

On the other hand, if you have a <sect1> that contains many long <sect2> sections you might want to put each <sect2> section in a separate chunk:

<sect1 id="sect.with.large.sect2" chunked="1">

Common to all elements is that they have an id attribute that can be used to identify the element with. The value must be unique for the entire documentation. Most of the elements that are used inside the BASE documentation do not need to have an id if they do not are used in any cross references from other part of the text.

There are some elements that always should have the id set. Which these elements are and how the id should look like for each one of those is described below. All values should be as short as possible and associated to the current element. The id value should only consist of the lowercase characters a-z, '_' instead of blank spaces and '.' to symbolize the different levels in the document.

This documentation is also use to create the help texts that show up in the web client when clicking on the question mark icons. The parts of the text that also should be used as help texts in the web must be inside <helptext> tags. These texts will be exported to a XML-file at the same time as the HTML-documentation is generated. The generated XML-file is compatible with the help text importer in BASE and will be imported when running the update script or installation script.

	Note
	The <helptext> must be outside the <para> tag but inside a <sect> tag to work properly. Do not put any <sect> tags inside the helptext. This will make the automatic chapter and section numbering confused.

The tag supports the following attributes

<sect1>
   <helptext external_id="helptexts.external.id" title="The title">
      The text that also should be used as a helptext in the program.
      <seeother>
         <other external_id="other.external.id">
            Related info here...</other>
      </seeother>
   </helptext>
</sect1>

<nohelp>see <xref linkend="chapter11" /></nohelp>

<seeother>
  <other external_id="userpreferences.password">Change password</other>
  <other external_id="userpreferences.other">Other information</other>
</seeother>

ant docbook
ant test
cd build/test
./run.sh TestHelp

Images and figures are normally implemented like the following example. The image-file must be located in doc/src/docbook/figures, otherwise the image will not be visible in the generated output files.

<figure id="docbook.figures.menuchoice">
  <title>The home page</title>
  <screenshot>
    <mediaobject>
      <imageobject>
        <imagedata 
          scalefit="1"
          width="100%"
          fileref="figures/homapage.png" format="PNG" 
        />
      </imageobject>
    </mediaobject>
  </screenshot>
</figure>

Warning

When using images in docbook you will always have problems with image resolution and scaling. Since we are generating output for both HTML and PDF it is even worse. What we have found to work is this: The screenshots must be saved without any resolution information in them, or with the resolution set to 96 dpi. We have configured PDF to use 96 dpi instead of 72 dpi to make the HTML and PDF output look as similar as possible. Scaling in HTML has been disabled. The images will always be the same size (number of pixels) as they actually are. Please, do not make the screenshots too wide! Tip Change your BASE preferences, see Section 6.2.4, “Preferences”, to a smaller font size or use the zoom functionality in the web browser to make more information fit in the same image width. For small images, less than the width of the PDF page, do not specify scaling factors or widths. Images that are wider than the PDF page will be clipped. To prevent this you must add the following attributes to the <imagedata> tag: scalefit="1" width="100%". This will scale down the image so that it fits the available width. If you still need to scale the image differently in the PDF use the width and depth attributes.

Following describes how to insert an example in the documentation.The examples in this document are often some kind of program listing but they can still be examples of something else.

	Use spaces instead of tabs for indentation
	Use spaces for indentation in program listing, this is because of the tab-indentations will sooner or later cause corrupt text.

<example id="net.sf.basedb.core.plugin.Plugin.getAbout">
   <title>A typical implementation stores this information 
      in a static field</title>
   <programlisting language="java">
private static final About about = new AboutImpl
(
   "Spot images creator",
   "Converts a full-size scanned image into smaller preview jpg " +
	 "images for each individual spot.",
   "2.0",
   "2006, Department of Theoretical Physics, Lund University",
   null,
   "base@thep.lu.se",
   "http://base.thep.lu.se"
);
  
public About getAbout()
{
   return about;
} 
</programlisting>
</example>

The admonitions that are used in this document can be found in the table below.

Following items can be used to define different kind of lists in the documentation. Some common elements for the lists are also described here.

The example below shows how to create a list for term definition in the text.

<variablelist>
   <varlistentry>
      <term>Term1</term>
      <listitem>
         <para>
            Definition/explanation of the term
         </para>
      </listitem>
   </varlistentry>
   
   <varlistentry>
      <term>Term2</term>
      <listitem>
         <para>
            Definition/explanation of the term
         </para>
      </listitem>
   </varlistentry>
</variablelist>