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.

Most files in the documentation, except the index files, represents a chapter. Here is how to create a new chapter and include it in the main documentation:

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 3, 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 BASE 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 client 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 id="....">
   <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

Those who have checked out the documentation source from repository or got the source from a distribution package needs to compile it to get the PDF and HTML documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser Xsltproc is installed on the local computer. More information about XsltProc and how it is installed, can be found at http: / / xmlsoft.org/ XSLT/ index.html.

	Note
	There is an xml-parser in newer java-versions that can be used instead of XsltProc but the compilation will most likely take much much longer time. Therefore it's not recommended to be used when generating/compiling the documentation in BASE.

There are two different types of format that is generated from the documentation source. The format to view the documentation on-line will be the one with chunked HTML pages where each chapter and section of first level are on separate pages/files. The other format is a PDF-file that are most useful for printing and distribution. Those two types of output are generated with the ant-target: ant docbook. This documentation is also generated with ant dist, which will put the output files in the right location for distribution with BASE.

These elements should be used to mark up words and phrases that have a special meaning in a coding environment, like method names, class names and user inputs, etc.

<classname docapi="net.sf.baseb.core">DbControl</classname>

Follow one of the examples below to insert a method definition in the document.

<methodsynopsis language="java">
   <modifier>public</modifier>
   <type>Plugin.MainType</type>
   <methodname>getMainType</methodname>
   <void />
</methodsynopsis>

<methodsynopsis language="java">
   <modifier>public</modifier>
   <void />
   <methodname>init</methodname>
   <methodparam>
      <type>SessionControl</type>
      <parameter>sc</parameter>
   </methodparam>
   <methodparam>
      <type>ParameterValues</type>
      <parameter>configuration</parameter>
   </methodparam>
   <methodparam>
      <type>ParameterValues</type>
      <parameter>job</parameter>
   </methodparam>
</methodsynopsis>

Docbook has some elements that can be used to symbolize GUI items in a program. Following list contains the ones that are most common in this document.

<menuchoice>
   <guimenu>Administrate</guimenu>
   <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
   <guimenuitem>Overview</guimenuitem>
</menuchoice>

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.homepage">
  <title>The home page</title>
  <screenshot>
    <mediaobject>
      <imageobject>
        <imagedata 
          scalefit="1"
          width="100%"
          fileref="figures/homapage.png" format="PNG" 
        />
      </imageobject>
    </mediaobject>
  </screenshot>
</figure>

When taking screen shots of the GUI it is recommended to try to get a look and feel that matches the other screen shots in the documentation. Following is a list of "specifications" of how to get the look that is currently used in the documentation.

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 5.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.getMainType">
   <title>A typical implementation just return one of the values</title>
<programlisting language="java">
public Plugin.MainType getMainType()
{
   return Plugin.MainType.OTHER;
}
</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>