4. 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 [1] 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.

  1. DSSSL: Document Style Semantics and Specification Language. For more informations, you can visit the web site: http://www.jclark.com/dsssl/

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

1

defined that it is a XML document

2

the comments are writing between <!-- and -->

3

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

1.

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

2.

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

3.

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{ 1
};    

1

... comments ...

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