30.1. User, administrator and developer documentation with Docbook

30.1.1. Documentation layout
30.1.2. Getting started
Organization of source files
Create new chapter/file
Controlling chunking
The id attribute
Help text for the BASE web client
Build the documentation
30.1.3. Docbook tags to use
Text elements
Code elements
Gui elements
Images and figures
Examples and program listing
Admonitions
Lists
Link elements

This chapter is for those who intend to contribute to the BASE user documentation. The chapter contains explanations of how the documentation is organized, what the different parts is about and other things that will make it easier to know where to insert new text.

The documentation is written with the docbook standard, which is a bunch of defined XML elements and XSLT style sheets that are used to format the text. Later on in this chapter is a reference, over those docbook elements that are recommended to use when writing BASE documentation. Further information about docbook can be found in the on-line version of O'Reilly's DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner.

30.1.1. Documentation layout

The book, which is the main element in this docbook documentation, is divided into four separated parts, depending on who the information is directed to. What kind of documentation each one of these parts contains or should contain is described here below.

Overview documentation

The overview part contains, like the name says, an overview of BASE. For example an explanation about what the purpose with BASE is, the terms that are used in the program and other general things that anyone that is interested in the program wants/needs to know before exploring it further.

User documentation

This part contains information that are relevant for the common BASE-user. More or less should everything that a power user role or an user role needs to know be included here.

Administrator documentation

Things that only an administrator-role can do is documented in this part. It can be how to install the program, how to configure the server for best performance or other subjects that are related to the administration.

Developer documentation

Documentation concerning the participation of BASE development should be placed in this part, e.g. coding standards, the java doc from the source code, how to develop a plug-in etc.

In addition to the four main parts, there is also a FAQ part and an Appendix part.

30.1.2. Getting started

Before writing any documentation in BASE there are a couple of things, some rules and standards, to have in mind.

Organization of source files

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.

Create new chapter/file

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:

  1. Create a new XML-file in the folder for the part where the new chapter should be included. Give it a name that is quite similar to the new chapter's title but use _ instead of blank space and keep it down to one or a few words.

  2. Begin to write the chapter's body, here is an example:

    Example 30.1. Example of a chapter

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE chapter PUBLIC 
      "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
      "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    
    <chapter id="example_chapter">
       <?dbhtml dir="example" filename="index.html" ?>
       <title>Example of a chapter </title>
       <para>
          ...
       </para>
       <sect1 id="example_chapter.sect1">
          <title>Example of top level section </title>
          <para>
             ...
          </para>
          <sect2 id="example_chapter.sect1.sect2">
             <title>Example of second level section </title>
             <para>
                ...
             </para>
             <sect3 id="example_chapter.sect1.sect2.sect3">
                <title>Example of third level section</title>
                <para>
                   ...
                </para>
             </sect3>
          </sect2>      
       </sect1>
    </chapter>
    


    [Note] Note

    Do not forget to include the <?dbhtml> tag with the dir and/or filename attributes set to target folder and filename for the chapter.

  3. The last step is to get the new chapter included in the documentation. This is done by including the file's name in the file index.xml that's located in the current part's folder. The following example shows how the chapter that was created above is included in the user documentation part (as the last chapter).

    Example 30.2. Include a chapter

    <part id="user">
       <?dbhtml dir="user" filename="index.html" ?>
       <title>User documentation</title>
       <include file="overview.xml"/>
       <include file="webclient.xml"/>
       <include file="project_permission.xml"/>
       <include file="file_system.xml"/>
       <include file="jobs.xml"/>
       <include file="reporters.xml"/>
       <include file="annotations.xml"/>
       <include file="platforms.xml" />
       <include file="subtypes.xml" />
       <include file="protocols.xml"/>
       <include file="wares.xml"/>
       <include file="array_lims.xml"/>
       <include file="biomaterials.xml"/>
       <include file="experiments_analysis.xml"/>
       <include file="import_data.xml"/>
       <include file="export_data.xml"/>
       <include file="example_chapter.xml"/>
    </part>
    

    [Note] Order of chapters

    The chapters will come in the same order as they are included in the index file.

Controlling chunking

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">

The id attribute

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.

chapter

The chapter should have an id that is identical or almost identical to the chapter's title.

chapter_title

sect1-sect5

The creation of a section's id is done by combining an appropriate part of the parent chapter and/or section id with the current section's title (or part of the title). This rule may seem a little "fuzzy" but the aim is to not create too long id's yet they must still be unique. using the upper level's id and add the section's title or a part of the title. For a <sect2> the id could for example be created like this:

sect1_title.sect2_title

examples

The naming of an example's id is a bit different compare to the chapter's and section's id. It should begin with the chapter's id followed by examples and the caption of the example.

chapter_title.examples.example_caption

figures

The figure's id should have the following layout

chapter_title.figures.figure_name

Help text for the BASE web client

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] 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

external_id

Is used to identify and to find a help text in the web client. The BASE web client already has several IDs to help texts defined, it could therefore be a good idea to have a look in the program to see if there already is an external id to use for the particular help text.

title

Is directly connected to the name/title property for a help text item in BASE.

webonly

If set to a non-zero value, the contents of the tag will not be outputted in the HTML or PDF documentation. This is useful for minor functionality that is not important enough to be mentioned in the documentation but has a help icon in the web client.

Example 30.3. How to use the help text tag

<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>

Skip parts of a help text

From time to time, it may happen that you find that some parts of the text inside a <helptext> tag does not make sense. It may, for example, be a reference to an image or an example, or a link to another chapter or section. Put a <nohelp> tag around the problematic part to avoid it from being outputted to the help texts.

<nohelp>See <xref linkend="chapter11" /></nohelp>
Link to other help texts

You can use <seeother> and <other> to create links between different help texts. The <seeother> tag does not have any attributes and is just a container for one or more <other> tags. Each tag requires a single attribute.

external_id

The external ID of the other help text to link to.

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

We recommend that you place the links at the end of the help text section. The links will not show up in the HTML or PDF version.

Import help texts into BASE

Import the generated XML-file manually by uploading it from the data directory to the BASE-server's file system and then use the help text importer plug-in to import the help text items from that file.

The help texts can also be imported by running the TestHelp test program. In short, here are the commands you need to import the help texts:

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

Build the documentation

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] 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.

30.1.3. Docbook tags to use

The purpose with this section is to give an overview of those docbook elements that are most common in this documentation and to give some example on how they should be used. There will not be any detailed explanation of the tags here, instead the reader is recommended to get more information from Docbook's documentation or other references.

Text elements

Define Element to use Comments
Chapter <chapter>

See Example 30.1, “Example of a chapter”.

Title <title> See Example 30.1, “Example of a chapter”.
Paragraph <para> Used almost everywhere around real text.
Top-level subsection <sect1> See the section called “ The id attribute ”.
Second level section <sect2> See the section called “ The id attribute ”.
Third level section <sect3> See the section called “ The id attribute ”.

Code elements

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.

Define Element to use Comment
Class name <classname> The name of a (Java) class. The docapi attribute can be used to link the class to it's Javadoc (for the BASE API). This is done by setting the attribute to the package name of the class, like
<classname docapi="net.sf.baseb.core">DbControl</classname>
Interface name <interfacename> The name of an (Java) interface. Has a docapi-attribute which has the same functionality as in classname above.
User input <userinput> Text that is entered by a user.
Variable name <varname> The name of a variable in a program.
Constant <constant> The name of a constant in a program.
Method definition <methodsynopsis> See Example 30.4, “ Method with no arguments and a return value ”.
Modifier of a method <modifier> - " -
Classification of return value <type> - " -
Method name <methodname> - " -
No parameter/type <void> - " -
Define a parameter <methodparam> See Example 30.5, “ Method with arguments and no return value ”.
Parameter type <type> - " -
Parameter name <parameter> - " -

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

Example 30.4.  Method with no arguments and a return value

<methodsynopsis language="java">
   <modifier>public</modifier>
   <type>Plugin.MainType</type>
   <methodname>getMainType</methodname>
   <void />
</methodsynopsis>
which is rendered as: public Plugin.MainType getMainType();

Example 30.5.  Method with arguments and no return value

<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>
which is rendered as: public void init(SessionControl sc,
                 ParameterValues configuration,
                 ParameterValues job);

Gui elements

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.

Define Element to use Comment
Button <guibutton>  
Label <guilabel>  
Menu choice <menuchoice>  
Menu <guimenu>  
Submenu <guisubmenu>  
Menu item <guimenuitem>  
Icon <guiicon>  

Example 30.6. Describe a menu choice

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

In the text it will look like this: AdministratePlug-ins & extensionsOverview


Images and figures

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.

Example 30.7. Screen-shot in the documentation

<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>

which will generate an image like Figure 5.1, “The home page”.


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.

  • All screen shots are from Firefox and Windows 7. Popup windows in Firefox should not have the navigation toolbar (nor any other toolbars). Full windows should have the navigation toolbar. Replace the URL with base.onk.lu.se/demo/. Avoid extra toolbar buttons, etc. that are from plug-ins you may have installed in Firefox.

  • The default Windows 7 Aero theme is used with the Sky color theme, but we have disabled the transparency setting. This can be configured by right-clicking on the windows desktop and selecting Personalize. Then click on Window color near the bottom middle of the popup and uncheck the Enable transparency checkbox.

  • We have also disabled the Shadows under windows option. This is done from the Performace options dialog which can be found if you go to the Control panel ›› System ›› Advanced system settings dialog.

  • The screen shots have been taken with Shotty in high-quality mode and saved as PNG.

[Warning] 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] 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.

Examples and program listing

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.

[Warning] 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.

  • The verbatim text is split into several lines if the text contains more then 80 characters. This could give the text an unwanted look and it's therefore recommended to manually insert new lines to have control over layout of the text
  • We have added support for syntax highlighting of program examples in the HTML version. To enable it add a language attribute with one of the following values: java, javascript xml or sql. The highlighting engine support more languages. To add support for those in docbook, change the customized.chunked.xsl file. The syntax highlighting engine doesn't handle docbook markup inside the <programlisting> tag very well. You should avoid that, by using text-only examples withing a <![CDATA[ ... ]]> section. By default, Java program examples include line numbering, but XML examples don't. To disable line numbering for Java add :nogutter to the language attribute: <programlisting language="java:nogutter">. To enable line numbering for xml add :gutter to the language attribute: <programlisting language="xml:gutter">.

Example 30.8. Example in the documentation

The code below is used to create Example 26.2, “A typical implementation just return one of the values”.

<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>

Admonitions

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

Define Element to use Comment
Warning text <warning>  
Notification text <note>  
A tip <tip>  
Important text <important>  
Something to be cautious about <caution>  

Lists

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

Define Element Comment
None-ordered list <itemizedlist>  
Term definition list <variablelist>  
Ordered list <orderedlist>  
List item <listitem>  

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

Example 30.9. Example how to write a variable list

<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>

which is rendered as:

Term1

Definition/explanation of the term

Term2

Definition/explanation of the term


Link elements

Define Element Comment
Cross reference <xref linkend=""> Use this to Link to other parts of the document.
Cross reference with own text <link> Can be used as an alternative to xref
External URLs <ulink url="">  

Example 30.10. Links

<xref linkend="docbook.usedtags.links" />
<link linkend="docbook.usedtags.links">Link to this section</link>
<ulink url="http://base.thep.lu.se">Base2's homepage</ulink>

The first element will autogenerate the linked section's/chapter's title as a hyperlinked text. As an alternative to xref is link that lets you write your own hyperlinked text. The third and last one should be used to link to any URL outside the document.