Documentation Guidelines

Some antisocial English recommendations
Here are the most frequent mistakes once seen in user documentation. A well written documentation makes the learning curve less steep for potential users and support the profesionnal look of the software.
Use a spellchecker. This finds words like "choosen", "choosed", "chosed" (the correct form is "chosen").
Do not repeat things when they are totally obvious. For instance, when there is a button "Add Server", do not write "To add a server, click on Add Server button." This is boring for the reader, who then pays less attention. Another example: "colorScale", documentation: "This is the color scale used". Here, the documentation brings no information.
English details (that the spellchecker will not find):
"mouse button pressed down" and variants -> "click"
no space before punctuations in two parts (i.e., as opposed to French, no space before ";:!?")
Writing good documention is hard, it requires adopting the reader point of view: which question does she have? what is surprising for someone new to Tulip? what will she chafe at?

Definitions
Docbook is a collection of standards and tools for technical publishing. A Docbook file is composed of SGML() tags and is also dependant of a Document Type Definition(). Docbook has defined standard DTD that you can find in the docbook tools.
DTD : Document Type Definition. The DTD defines the vocabulary of content elements that an author can use and how they relate to each other. For example, a book element can contain a title element, any number of para elements for paragraphs, and any number of chapter elements.
SGML : Standard Generalized Markup Language, XML : Extensible Markup Language
XSL (Extensible Stylesheet Language) is a language of description used for the transformation of the sgml file into formatted ouput: XSL processors like xsltproc, saxon or xalan, ... do that.
Catalog : In XML, it provides a mapping from generic addresses to specific local directories on a given machine. A catalog can be used to locate the DocBook DTD, system entity files, and stylesheet files during processing.

Tools installation

Docbook XSL Stylesheet
There is a great reference for installing tools : Docbook XSL : the guide.
To write a manual using Docbook and the XSL stylesheets, we need four tools :
Docbook DTD
Docbook XSL stylesheets
XSL processor
XSL-FO processor (optional)
There are RPM (docbook-dtds, docbook-style-xsl), Debian (docbook-xml, docbook-xsl) packages for Linux systems, Fink packages for Mac systems, and Cygwin and other packages for Windows systems. The installation of Docbook and the XSL stylesheet create a file named /etc/xml/catalog. It contains the informations about all others catalogs to resolve the path of the DTDs and the stylsheets from the URI.

Manual Installation : Docbook XSL stylesheet
As we have some problems with the DTD provided by the distributions, Tulip gives the DTD 4.4 of Docbook XML and is located in $TULIPDIR/docs/common/dtd. So, this section is for informations. The XSL packages seem to have great catalog resolutions, but if you have problems, this section can help you.
If you need another solution or you have problems for the compilation, you can download the source package on oasis web site for Docbook and on the SourceForge page of XSL stylesheets. The Docbook sources are in a zip file. Unzip your package in a directory in the place you prefer. The Docbook XML DTD consists of a main file docbookx.dtd, several module files and a catalog file, named catalog.xml. To update the changes of location of your DTD, edit the file CatalogManager.properties in $TULIPDIR/docs/common/. Add the catalog file with its asbolute path to the catalogs variable.

CatalogManager.properties :

catalogs=/etc/xml/catalog;/home/bardet/docbook-4.4/catalog.xml
relative-catalogs=false
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1

Concerning the XSL stylesheet package, you just have to do the same thing. You can execute the script of intallation. You have to add the reference of the catalog too. Edit the file catalog.xml and complete the catalogs variable with the reference of the catalog of your XSL stylesheet. This catalog resolution make sure that the path, the differences could be find in all Operation Systems.

XSL processor
Currently, there are three to do XSL Transform processing with the recommendations of XSL : saxon (), xalan (), and xsltproc (). For the Tulip project, we have decides to use Saxon for the XSL processor. Xsltproc is the xslt c library for gnome. This program is a way to use the library libxslt with a command line tool for applying XSLT stylesheets to XML documents. This application runs quickly but does not include the implementation of the extensions. Xalan is an other solution but Saxon is the most recommanded.
Saxon is a free processor written in Java, so it can be run on any operating system with a modern Java interpreter. To install it, you have to download on sourceforge the last release 6.5.4. for debian, it exists a deb package. This is the full version that implements the XSLT 1.0 standard. It runs on Java system and provides opportunities for extensions. For Windows, it exists the Instant Saxon a precompiled version that runs only on Microsoft Windows. Saxon is distributed as a zip package. You have to unzip it into a suitable location. It gives three .jar files ; saxon.jar contains the XSLT processor. In according to the location, you have to update your CLASSPATH. You need to include the full path to the necessary .jar files in the CLASSPATH environment variable. To update it :

CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\
/usr/docbook-xsl/extensions/saxon653.jar
export CLASSPATH

If your CLASSPATH is incorrect, you get an error message about NoClassDefFoundError. To generalize it, you have to change your .bashrc or .bash_profile. In this example, a second package is included : /usr/docbook-xsl/extensions/saxon653.jar, in Fedora Core 4, it is located in /usr/share/sgml/docbook/xsl-stylesheets/extensions/. It contains the implementation of the extensions of XSL Transformations. This extensions are necessary to manage some tags and are included in the docbook tools. The general syntax for compilation is like followed :
java com.icl.saxon.StyleSheet options file.docbook file.xsl param=value
However, Tulip provides the sources of saxon and you do not worry to this installation to avoid the complicated installation.
This system of catalog resolution is made for finding located files. With the packages of Fedora and perhaps with others distribution, the catalogs include a declaration with URL adresses. So the catalog resolving processor try to connect on the Net.

<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN"
"http://www.oasis-open.org/commitees/entity/release/1.0/catalog.dtd">

It should be erased in all catalog files which blocks the offline compilation (/etc/xml/catalog, /usr/shar/sgml/docbook/xmlcatalog, ...).

XSL-FO processor for PDF output
To transform the docbook sources in pdf documents, we need to use an other format FO. It is running with a stylesheet in docbook-xsl package. The role of the XSF-Fo processor is to transform FO files in printable files, like pdf. You have to install passivetex. Fedora and Debian includes this package, but you can download and install it with its web site, . It exists a program named pdfxmltex giving tex macros for the XSL-Fo processing.

Doxygen
It can already be in your distribution. For distributions like Debian or Fedora Core, you can used :
yum install doxygen
apt-get install doxygen
For another solution, you can find source files and CVS repository in the web site of Doxygen ().

Handwriting for the manuals
Some works on the Tulip project lead to make a part of a handbook for developer or users. Docbook utilities are used to create them.
Docbook is a DTD (Document Type Definition) for XML or SGML document that define elements. It is a kind of grammar of the source document. This is in relation with stylesheets (DSSSL [] or XSL) which allow you to publish on the Web ( in HTML, XHTML) on a printable documentation (PS, PDF, RTF...) with your Docbook documents. The main advantages of the docbook format is the possibility to seperate the contents of the forms. The tools which can transform the source documents are generic and can pratically run on all Operation Systems. Docbook is the successor of LinuxDoc.
For Tulip documentation, the source documents are in XML, because XML leads to take the place of SGML to alleviate compatibility problems with browser software. It's a new, easier version of the standard rules that govern the markup itself. To find all of the xml elements to composed your own document, you can see : http://www.docbook.org/tdg5/en/html/pt02.html
For each document, a set of XML files should be created. To help the editing of the handbook, it is possible to use general editors like kate, emacs, quanta. See Docbook Editors. To configure Kate, select Configure Kate -> Settings -> Configure Kate. Select the plugin item from the application tree and check the Kate XML Completion, and the Kate XML Validation boxes.
To compile the handbooks, you just have to type make html. If you want to test the validation of the sources of the handbooks, type make check. The last command is make pdf, it produces the printable output.
DSSSL: Document Style Semantics and Specification Language. For more informations, you can visit the web site:

Some Tricks

<?xml version='1.0'?>
<!-- My first Docbook file -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN"
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

defined that it is a XML document
the comments are writing between <!-- and -->
DTD, Document Type Declaration with pulic identifier
The identification of the DTD is used by the document to know which root element is. The declaration could have a different aspect if you use the system identifier : <!DOCTYPE book SYSTEM "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> Here, OASIS is the owner, the declaration is DTD Docbook XML V4.4 and the language is English EN. The keyword book specifies that the root element is book. An example of the structure of a Docbook file is like followed.

  
<!DOCTYPE book SYSTEM 
    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book> 
    <bookinfo> 
    <title>My First Book</title>

        <author><firstname>Jean-Pierre</firstname><surname>DUPONT
                    </surname></author>
        <copyright><year>2005</year>
                      <holder>Jean-Pierre DUPONT</holder>
          </copyright>
    </bookinfo>
    <preface> ... </preface>
    <chapter> ... </chapter>
        <sect1> <title>..</title>
            <para> ...</para>
        </sect1>
    <chapter> ... </chapter>
    <chapter> ... </chapter>
    <appendix> ... </appendix>
    <appendix> ... </appendix>
    <index> ... </index>
</book>

Each blocks of text is in a para element.

Validation
The validity of a document is very difficult to detect, so we use a program to do that. A validating parser is a program that can read the DTD and determine whether the exact order of elements in the document is valid according to the DTD.
To determinate if the XML code is valid, the program xmllint can be used with the option --valid. This program is a parser dependent of the library libxml2.
xmllint --valid --noout myfile.docbook
When there are errors in the document, xmllint detects the number line and displays the form that it should be.

index.docbook:485: element sect2: validity error : Element sect2 
content does not follow the DTD, expecting (sect2info? , (title , 
subtitle? , titleabbrev?) , (toc | lot | index | glossary | 
bibliography)* , (((calloutlist | glosslist | bibliolist | itemizedlist
| orderedlist | segmentedlist | simplelist | variablelist | caution |
important | note | tip | warning | literallayout | programlisting |
programlistingco | screen | screenco | screenshot | synopsis |
cmdsynopsis | funcsynopsis | classsynopsis | fieldsynopsis | 
constructorsynopsis | destructorsynopsis | methodsynopsis | formalpara
| para | simpara | address | blockquote | graphic | graphicco | 
mediaobject | mediaobjectco | informalequation | informalexample | 
informalfigure | informaltable | equation | example | figure | table |
msgset | procedure | sidebar | qandaset | task | anchor | bridgehead |
 remark | highlights | abstract | authorblurb | epigraph |indexterm | 
beginpage)+ , (refentry* | sect3* | simplesect*)) | refentry+ | sect3+ |
 simplesect+) , (toc | lot | index | glossary | bibliography)*), got (
refentry)
</sect2>
                   ^
make: *** [check] Erreur 1

It exists several attempts to produce an print or web publishing. Recently, the XML workgroup has made a standard Extensible Style Language (XSL). It provides a set of stylesheet able to transform the Docbook documents. DSSSL is an other possibility, but we use the XSL stylesheet for the Tulip project. This stylesheet is an argument for the compilation with an XSL processor for the XSL transformations.

Docbook FAQ
how to separate the work in several files ?
The first solution to write a part of a handbook is to complete the main document. To avoid that several persons work on the same file, it exists a solution to cut the docbook file. You can write a section or a chapter and you just have to include your part in the main file. To create a valid file for the compiler, you shoud modify the head of a docbook file and specify the kind of document you do. For a chapter, your file is like followed :

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD Docbook XML V4.4//EN">
<chapter> 
    <title>My personal Chapter</title>
    <sect1> ... </sect1>
</chapter>

The identification gives the kind of file you write. For including your work, you just have to complete the declaration of the main file and insert a special tag located at the place that you want the inclusion. Don't forget to erase the declaration of your work. The file must begin with the markup chapter.

<!DOCTYPE book PUBLIC "-//OASIS//DTD Docbook V4.4//EN" [
  <!ENTITY myPersonalFile SYSTEM "myFile.xml">
]>
<book>
...
</chapter>
&myPersonalFile;
<chapter>
...

How to insert a figure ?
the element uses for the insert of a figure is <figure>. It enables the numerotation of the figures. Warning, the width of the figures should not exceed a certain value to avoid that it is truncated in the pdf transform. You can specify a title and other parameter in the limits of the DTD.

<figure> <title>Screenshot of the result</title>
<graphic fileref="doxygen-ex.png"/></figure>

In order to insert a figure as inline, use the tag inlinegraphics
How to make annotation in a program listing (or in a console listing) ?
See DocBook XSL : the complete guide
To do that, you use the set of tags programlisting, co, calloutlist, callout.

<programlisting>
class MyClasse{ <co id="myid" linkends="mylink"/>
};    
</programlisting>
<calloutlist>
    <callout arearefs="myid" id="mylink">
        <para>... comments ...</para>
    </callout>
</calloutlist>

The programlisting contains the program that you want to display. It is a verbatim mode. Warning, special caracters could be not allow : <, for example. The code element represents the callout you want to place. The location of the insertion is important because it is the location on display. Two attributes are essential : id for the identification and linkends for indicate which comments is linked with the callout. After the programlisting element, we use a calloutlist element to define a list of comments. each comment is contained in a callout element. It has attributes whose arearefs to make a reference to callouts and id for the identification.
It exists an other solution but it is more difficult. You have to specify coordinates of place where you want a callout. This solution is an easy and quick way to comment your program listing.

class MyClasse{ 
};

... comments ...
To adapt the case to the console listing, you should use the screenco, screen, callout, ... elements.

Code documentation

Presentation
Doxygen is a documentation system for several languages like C++. It can generate an on-line documentation browser (in HTML), a set of manpages, an off-line reference manual (in LaTeX) and/or others from the set of documented source files of your project. This kind of documentation is a necessary tool for developers to find informations about the code. It is not a way to explain how it is imagined but which possibilities you have. It is available for several distributions like Fedora Core, Debian, Gentoo and others,.. Windows, MacOs and Sun Solaris too.
To create your first Doxygen documentation, you need a config file .cfg or .doxygen. To generate it :
doxygen -g myfile.doxygen
The file contains the options you can choose for the documentation generation. Comments indicates how to use this variables. The INPUT variable contains the files or directories to find the source files. When you have set all tags with good values, you can generate the documentation. Doxygen checks the source files to extract the informations in special comments and tags. See this page for the informations about the variables : http://www.stack.nl/~dimitri/doxygen/config.html. To create it :
doxygen myfile.doxygen
By default, it creates directories : html, latex, and/or man, ...
For the Tulip project, It exists two documentations. One is destinated for the Developer team and this other one is for the user of the librairies. The Configuration files are generated by the Makefile processing.

Developer comments
The code documentation, generated by Doxygen is completely dependant of the developer comments. It is important that developers follow the grammar rules.
So the blocks of documentation in the sources files are the C++ comment blocks. For each item of code, there are two types of descriptions, which together form the documentation : a brief description and detailed description. A detailed description is used to explain generously the existence of an item.

/**
* detailed description
*/

or 

/*!
* detailed description
*/

or 

/*!
 detailed description
*/

or others ....

To make a brief description, you can use the command \brief. This command ends at the end of a paragraph, so the detailed description follows after an empty line. An other option is to use a special C++ style comment which does not span more than one line.

/*! \brief Brief description.............
*         ...............
*
*  Detailed description
*/

or 

/// Brief description 
/** Detailed description. */

or 

//! Brief descripion.

//! Detailed description 
//! starts here.

or others ....

For more details, the web site of Doxygen explains it. In general, the comments must be before the declaration or definition of a type, a function or a member. If you want to putting the documention after, you have to add a marker <. Note that you can place your comment at other places using some tags like \class, \union, \fn, \var, ... or @class, @union, @fn, @var, ...
It exists several tags to help you for commenting and writing a description : all of it begin with a backslash \ or an at-sign @.
@author, name of the author.
@param, to write a special comment on a parameter of a method or function
@see, to make a reference to an other object or function
@return, to indicate the exit of a function
@date, date of creation
@note, describe a role
@attention, write a caution
@warning, write a warning
@pre, write a prerequisite
@remark
The complete list is on this page in the Doxygen web site.

Doxygen : A simple source file

// ... comments not include  ...
///  A example of class : MyClass. 
/**
    a more detail class description :
    \author Me
    \date 29/07/2005
*/
#include <string>
class MyClass
{


    /* ... comments not include ... */
    public:
        /** the constructor of the class */

        /**  the detail description of the constructor. */
        MyClass(){i=0;}
 
        //! A destructor.
        ~MyClass(){}

        /// drawing of a string
        /**
            \param s the string to display
            \return there is no return
            @sa MyClass(), ~MyClass()
        */
        void draw(const char *s="Hello World");

        /* exemple of doc comments not before the declaration */
        unsigned int getI(){return i;} /**<@return the number 
                                                the value of i */
    private:
        unsigned int i;


    /** @var i
        @brief, you can put the comments where you want 
                                    with the special tags */
};

To update the Documentation of Tulip, you just have to use the makefile and so write : make docs.

Doxygen FAQ
How to insert a block of code ?
To illustrate your documentation, you can insert a block of code in a description between \code and \endcode. This code is written in the documentation with highlighting syntax.
How to force an end of line ?
Use the tag \n.
How to make doxygen ignore code fragment ?
It exists two ways to resolve this questions. The first one is to use the tags \cond and \endcond to skip the internal code. The second way is to use the preprocessor of Doxygen. In the configuration file, you specify the macros and you verify if the value of PREPROCESSING is to yes. Then, you set MACROS_NAME to PREDEFINED.

#ifndef MACROS_NAME

 /* code that must be skipped by Doxygen */

#endif /* MACROS_NAME */

Two macros are defines for Tulip documentations.
DOXYGEN_NOTFOR_DEVEL : use to skip the code for Developer and User documentations.
DOXYGEN_NOTFOR_USER : use just for the User documentation.
How to insert a equation ?
See the Doxygen web site
Doxygen allows you to put Latex formulas in the ouput (just for HTML and latex format). Three ways are avaible. If you want to include formulas in-text, you have to put formulas between a pair of \f$

\f$ AB = \sqrt{BC^2 + CA^2} \f$

The second way is for a centered display on a seperate line. These formulas should be put between \f[ and \f] commands.
The third way is to used formulas or other latex elements that are not in a math environment. It can be specified using \f{environment}, where environment is the latex environment, the corresponding end commands is \f}

References
Docbook XSL : the complete Guide http://www.sagehill.net/docbookxsl/index.html
The Duck Book - Docbook : the Definitive Guide
The KDE documentation primer : recommandations to write correctly in Docbook - http://i18n.kde.org/doc/doc-primer/index.html
Doxygen web site - http://www.docbook.org/tdg/en/html/part2.html