[OpenSER-Docs] some primers on docbook, system setup and other tools

[Henning Westerholt]

Hi all,

for the people just joining this list and wondering what its all the fuss 
about the docbook-xml stuff and such..

Docbook XML is a documentation metaformat, that allows the (relative) easy 
creation of documentation for computer science related stuff. It supports the 
generation of HTML, PDF and other formats from one XML/SGML source.

There exists a quite good (and short) tutorial for docbook-xml, which covers 
also the documentation generation with the old and new toolset at:

http://opensource.bureau-cornavin.com/crash-course/en/index.html


To generate the documentation from the docbook source there are several 
packages necessary, for example on a debian system: docbook, docbook-dsssl, 
docbook-utils, docbook-xml, docbook-xsl, xsltproc and lynx.

To test if your installation is complete, run this commands on a svn checkout 
of the openser:

- make modules-readme (creates the README documentation for all modules, test 
  old docbook conversion process)
- make dbschema (creates database schemes with xsltproc)

After this two steps the READMEs and the DB schemes should be updated as you 
could check from the file modification stamp.


I personally edit docbook files with a good texteditor or directly in the IDE, 
for example kate or kdevelop on KDE. There exists probably many other 
capabable editors.

Changes to existing files or new content should be posted as "patch" to a 
recent trunk version. This patches could be created with the 'svn diff' 
command. A good book for understanding subversion is available at 
svnbook.org.

This patches can be reviewed for correctness with any text editor, most 
understand this format and also syntax highlight them. There exists also 
graphical tools that display the differences more nicely. For KDE a good one 
that i use is 'kompare'.

Cheers,

Henning