This file contains the minimal knowledge needed to write or maintain
documentation. It also provides a detailed explanation about the
framework and how the build system works.

This first draft is dedicated to everyone who wants to write, port
(from 24.1.x to 3.0) or proof-read documents written for the RTAI
project.

1. Using the build system to write documentation.

There are two ways to write documentation: Doxygen and DocBook XML. Doxygen
documentation is extracted from source code comments, and hence better suited
for API documentation. DocBook shall be used for documents separated from
sources, like a reference manual or an installation guide.


1.1. Common part.

The build system try to behave consistently across the two
documentation subdirectories, so there are a few common elements.

Each documentation system can be enabled or disabled separately. When
a documentation system is disabled the "make" command doesn't have any
effect, whereas "make install" and "make dist" use the generated
documentation contained in the doc/generated subdirectory. On the
other hand, when a documentation system is enabled, typing "make"
generates the documents which will be installed after invoking a "make
install" command and copied to doc/generated when typing "make
dist".

The suppported documentation formats are ps, pdf and html. Each html
document generated in the build directory is browsable in order to
ease the development cycle. Modifying the sources and typing make in
the build directory is then enough to notice the result. The ps and
pdf files can be similarly exploited in the build directory.

Adding a new document requires the following steps:
- add the generated document name (directory for html, file for ps and pdf) to
  the HTML_DOCS, PS_DOCS or PDF_DOCS variables of GNUmakefile.am ;
- add the generated documents in the "generated" directory.

The makefiles rules shall be enough to discover the source file names
and keep track of the dependencies of the generated document files
names.


1.2. Doxygen.

The Doxygen documentation sources shall be written by two different ways:
- as comment blocks in the sources;
- in separated files with the .dox extension (the doc/doxygen already
contains some .dox files which can be used as examples.)

The Doxygen documentation is produced as html files in the api
subdirectory of the doc/doxygen. The latter is actually located
in the build tree and the api subdirectory shall be generated
everytime "make" is typed because the dependencies are difficult to
track.

In order to avoid cluttering RTAI code with too many comments, it is
advisable not to use comment blocks in the code when they do not refer
to a code entity (like functions, macros, etc.)

The Doxygen documentation block style chosen for RTAI is the Javadoc
style. Each comment is introduced with the /** sequence of characters
and the tags shall begin with the @ character.

Another important detail about RTAI Doxygen documentation is the use
of the so-called Doxygen documentation groups. A group is a way to
logcially group different entities, such as grouping several files in
a module. These groups are a chance to describe the RTAI structure in
a top down approach making them visible in a "modules" section of the
generated documentation. This kind of presentation make it easier for
the user to search and find quickly relevant information. Initially,
the structure of these groups was the same as the one used in the RTAI
manual.

A group is defined with the "defgroup" tag. Other entities may be
placed in this group, either using the "ingroup" tag, or surrounding
several entities with the /*@{*/ and /*@}*/ blocks.

Needed tools: The minimum version of Doxygen needed to build
documentation is 1.3.4. If configure detects "dot", a tool belonging
to the "graphviz" package, configure will set the INCLUDE_GRAPH to YES
in Doxygen configuration file, so that Doxygen will generate, for each
source file, a "clickable" graph showing its include dependencies.


1.3. DocBook XML.

The DocBook XML documentation sources and their GNUmakefile may be found in the
doc/docbook directory and its subdirectories.

In order to generate documentation from DocBook XML sources, you will need the
following tools :
- xmllint (part of the libxml2 package) for validation;
- xsltproc for HTML and FO generation;
- FOP for conversion from FO to PDF, fop is a java program and uses the JAI
  library (JAI stands for Java Advanced Imaging), so you will need a working
  JRE, the JAI library 
  (http://java.sun.com/products/java-media/jai/current.html) and, of course FOP,
  (ftp://ftp.inria.fr/pub/Apache/xml/fop);
- Docbook XML DTD (RTAI documentation uses the 4.2 DTD version);
- Docbook XML stylesheets (XSL) for use with xsltproc to process the XML source
  files.

The configure script, when launched, will look for theses different elements:
- the xmllint, xsltproc and fop.sh programs must be found in the directories of
  the PATH variable;
- the docbook XML and docbook XSL root directories are searched in
  their distribution specific places but may be overriden with the
  appropriate configure options. Note that if you installed your
  distribution standard packages for these files, and they are not found
  by the configure script, please report the problem to the
  rtai@rtai.org mailing list using a [DOC] tag in the subject of your
  message.

A GNUmakefile.am to compile some Docbook XML documentation should
define some variables and include the file docbook.rules. The
variables of interest are:
- DBX_HTML_DOCS and DBX_PDF_DOCS, which define the final documents
 (directories names for html and .pdf files for pdf), the corresponding
 xml sources are found by the usual extensions substitution rules;
- DBX_HTML_CSS is the name of the css used by the generated html documentation,
  the corresponding file should be found in the source tree i.e. in the
  doc/docbook/css subdirectory;

- DBX_HTML_STYLESHEET and DBX_FO_STYLESHEET are the name of the xsl
  files used by xsltproc to generate the html directories (or .fo files)
  from the corresponding xml files, these files may be given as a path
  relative to the source dir or to the build dir.

If the XML source references some image files, they shall be included
in the doc/docbook/pictures files.

In the RTAI DocBook documentation system, a customized "chunk.xsl"
stylesheet is provided to generate chunked html documentation from xml
files. This customized stylesheet uses the rtai-titlepage.xsl itself
generated from rtai-titlepage.spec.xml. All these files may be found
in the doc/docbook/custom-stylesheet/xsl/html directory. A
customized stylesheet for use in conversion from xml to fo is also
provided in the doc/docbook/custom-stylesheet/xsl/fo directory.


1.4. Generating the "generated" directory.

In order to ease the maintenance of the generated documentation, a script was
made to keep the doc/generated cvs directory synchronised with the current
state of the documentation. This script is named generate-doc-and-commit and
does the following :
- run make dist in the build tree (hence generating, as a side effect, a
  "generated" dir from the last generated files if all documentation systems are
  activated) ;
- compare the contents of this directory with the contents of the source
  directory, so as to note the name of the removed files and of the new files
  and directories ;
- copy the contents of the new generated files in the source tree, overriding
  the old files with the new ones ;
- remove the obsolete files and run the proper cvs remove commands ;
- run cvs add to add the new directories, then run cvs add to add the new
  files.

Typing "cvs commit" is then enough to save the changes in the cvs repository.




2. Internals.

2.1. Installation and distribution.

As mentioned in the first part of this document, installation and
distribution work consistently for the three documentation
systems. This common behavior is handled by the
doc/install-dist.rules file which is included by the latex and
doxygen directories Makefiles as well as the docbook.rules making all
the files of the docbook directories include it also.

The list of files to be installed are contained in the HTML_DOCS,
PDF_DOCS and PS_DOC variables. The names of the directories where they
are copied from are contained in the HTML_DOCSDIR, PDF_DOCSDIR and
PS_DOCSDIR variables.

The configure options --enable-dox-doc and --enable-latex-doc (defined
in configure.in) and --enable-dbx-doc (defined in
base/config/autoconf/docbook.m4) are used to define automake
conditionals CONFIG_RTAI_DOX_DOC, CONFIG_RTAI_LATEX_DOC and DBX_DOC,
which, in turn, are used by the automake generated Makefiles to
correctly define the *DOCSDIR variables.

install-dist.rules does not define directly the install-local, dist-hook and
uninstall-local targets, automake does not seem to like multiple defined
targets, yet supported by make.



2.2. Doxygen

The rules to generate the Doxygen documentation are fairly simple and were
directly added in the Makefiles where they are used. The Makefile for Doxygen
is so simple that it does not require a separated rule file.

2.3. DocBook XML

As mentioned section 1.4, the Makefile rules used to generated
documentation from their DocBook XML is contained in
doc/docbook/docbook.rules. What is explained here is to help the
documentation writer understand why this file looks like the way it
does.


2.3.1. Portable DocBook XML sources.

The first problem of DocBook XML is the way to create portable
references to the DTD and XSL files. The only way seems to declare
these file names as HTTP URL, and then find the corresponding local
files with a catalog file passed (through the SGML_CATALOG_FILES
environment variable) to all XML tools.

In order to avoid leaving this problem to the people writing DocBook
documentation, the configure script allow the user to specify the DocBook XML
DTD and XSL root directories. If they are not specified, the configure search
them in the distribution specific directories (the list of distribution-specific
directories may be extended by modifying the docbook.m4 file). Finally, a
configure option let the XML tools use the network (not used by default, and if
you plan to activate this option, you should install a web cache or be prepared
for long compilations). 

If configure does not find a way to access the DocBook XML DTD and XSL, it 
fails. Otherwise the directories where the XML DTD and XSL files may be found
are used by configure to produce a catalog file (doc/docbook/catalog) in
the build tree. docbook.rules then defines the SGML_CATALOG_FILES environment
variable to point to this file.


2.3.2. Directories problems.

The next problem of DocBook XML is the lack of a '-I' option to
xsltproc or an equivalent way to parametrize the xsl:include or
xsl:import directive. More precisely: the XSL used to convert XML to
HTML (named chunk.xsl) needs to include a generated titlepage XSL file
from the build directory which cannot be known in advance when writing
the source files.

For this reason, doc/docbook/custom-stylesheets/xsl/html/chunk.xsl is
generated by configure in the build tree from
doc/docbook/custom-stylesheets/xsl/html/chunk.xsl.in.

Conversely doc/docbook/custom-stylesheets/xsl/fo/docbook.xsl has
to be taken from the source tree, so finding the XSL stylesheet, as
provided by the DBX_HTML_STYLESHEET and DBX_FO_STYLESHEET variables,
had to rely on the VPATH mechanism. This is achieved in making the
DocBook documents Makefile targets depend on their respective
stylesheets (which is better anyway).

Another directory problem occurs when trying to generate HTML
documentation in a sub-directory of the current directory. In order
for that documentation to remain browsable in this directory, it has
to make reference to pictures and css in the source tree. The problem
was then to be able to find the source directory from one level below
the current directory. This looks simple, but the answer depends on
whether the source directory is known as a relative path or as an
absolute path. So, docbook.m4 tests whether the source directory was
passed as an absolute or a relative path and defines the
DBX_ABS_SRCDIR automake conditional, and this conditional is used by
docbook.rules to define the variable html_srcroot to be the path to
the DocBook documentation source root (that is doc/docbook) from
any sub-directory of the current build directory.


2.3.3. HTML installation and distribution.

As mentioned in the previous section, the generated HTML documentation can be
browsed in the build directory and, for this reason, makes reference to files
(namely pictures and CSS) in the source tree. But on the other hand, once
installed, it can not make reference to files in the source tree, so it has to
be transformed for the installation and distribution.

This is done with a sed command, passed to the HTML installation and
distribution rules as the DBX_HTML_TRANSFORM variable. This variable value is
'cat' when installing the documentation from the "generated" directory (that is,
when the automake conditional DBX_DOC is false), since the generated
documentation is expected to have already been transformed.
