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

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