February 2008 - sr-docs

[OpenSER-Docs] First Clean-up Patch for Documentation
by Edson 04 Mar '08

04 Mar '08

Hi, Guys... I finish the first clean-up of the documentation. It consisted by: 1) remove all FAQ and DEVEL files considered empty in content (no content at all or just the default lines); 2) remove of the <RevHistory>/</RevHistory> tag (and of course anything Between them); 3) remove the comments at the EOF that beginned with "<!-- Keep this element at the end of the file"; The attached file (in ZIP format) is the resulting SVN DIFF file. It was applied over trunk version, revision 3761. I would like to ask the developers how much is a good time to wait for comments and revisions before commiting the changes? 1 week? 10 days? Sugestions? Edson

3 19

[OpenSER-Docs] Add examples in module documentation
by Iñaki Baz Castillo 03 Mar '08

03 Mar '08

Hi, for now they are just a few modules that include real examples in their doc. Usually, a module doc just shows examples of how to set each parameter or use each function, but there is not a "global" example. I don't know if would be good to include a section "Examples" in the module doc template (it could saturate the info), or maybe a section "Examples" containing links to the wiki or external references. What do you think about it? -- Iñaki Baz Castillo ibc(a)in.ilimit.es

4 7

[OpenSER-Docs] module docs - FAQ
by Henning Westerholt 29 Feb '08

29 Feb '08

Hi all, at the moment the modules documentation ships with this FAQ blocks that gives a few links to the openser homepage and the bugtracker, e.g.: http://www.openser.org/docs/modules/1.3.x/lcr.html#AEN424 Its necessary to include this kind of information at this place? The persons that reads the documentation probably already found the openser homepage.. ;-) Or perhaps this FAQ block should be extended? What do you think? Cheers, Henning

3 2

[OpenSER-Docs] some primers on docbook, system setup and other tools
by Henning Westerholt 27 Feb '08

27 Feb '08

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

1 0