[OpenSER-Docs] some primers on docbook, system setup and other tools
henning.westerholt at 1und1.de
Wed Feb 27 14:05:42 CET 2008
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:
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
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
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'.
More information about the sr-docs