Chapter 17. Writing Documentation

Table of Contents

UML Diagrams
UML Editing
Diagram Types

Documentation of the Lire project is done in DocBook XML 4.1.2. The Lire User's Manual has more information about DocBook.

After editing the Lire Developer's Manual or the Lire User's Manual, you should run make check-xml to make sure the document is still a valid DocBook document. You should fix any errors before commiting your changes.

If everything went right, documentation is build in txt, tex, html and pdf format by running make dist, or just make in doc/. We give some hints which might be helpful in case you'll have to build the documentation manually.

To generate PDF:

	  $ jade -t tex -d /path/to/DSSSL/docbook/print/docbook.dsl roadmap.xml
	  $ pdfjadetex roadmap.tex
	
The last step is actually done two or three times to resolve page numbers.

To generate HTML:

        $ jade -t sgml -d html.dsl roadmap.xml
      
And now use the html.dsl in the doc/source directory. (If needed adjust it to reflect the location of your DSSSL stylesheets). Use lynx to generate TXT output from HTML with:
	  $ lynx -nolist -dump roadmap.html > roadmap.txt
	

UML Diagrams

Unified Modelling Language (UML) is a set of definitions on how design diagrams are composed. These diagrams will help to document and understand the internals of Lire, and are used as such in this manual.

UML Editing

Several UML editors are available, but few are open source. Among these are Dia (general diagram editor for Gnome), ArgoUML (written in Java) and UML Modeler (UML specific editor for KDE). The latter was used to draw the diagrams found in CVS /service/doc/uml-diagrams.

Diagram Types

UML supports several diagram types. Two important ones are class diagrams and sequence diagrams. The former is used to depict the relations and associations between classes. Classes can be programs or modules. The latter is used to show how certain tasks are performed in time, and can be used to model the sequence of events.