[SR-Dev] Module Documentaiton (was: what to do if function names differ?)

[Henning Westerholt]

On Tuesday 21 April 2009, Martin Hoffmann wrote:
> Before sip-router started, I started an effort for SER to have all
> module documentation standardized into a manual page based on docbook
> sources.[0] The result is certainly optimal, for a user on a *nix system,
> doing "man tm" should be natural.

Hi Martin,

i also provided man pages for all kamailio modules with a similar approach like you did, by writing a XSL. But we don't used the docbook to man infrastructure like you did, instead we wrote a own small converter script.

Man pages in kamailio trunk and 1.5.0 release can be generated with make modules-docbook-man, and are also included in the debian packages, if you want to take a look. 

> The source format is dubious, though. I eventually ended up with docbook
> since it is a standard of sorts and there are tools to make manpages out
> of the sources (although they need some tweaking). However, editing is
> as painful as it gets.

I don't think that docbook is really that painful. If you look at a typical README source, e.g. for tm [1] then one needs to only master a few tags. This is not too hard, IMHO. 

> For documentation, painful editing usually means 
> it is not being done. So, if someone has a better suggestion for the 
> source format, they are most welcome. Some lightweight markup like RST
> is probably a good idea, but then someone needs to write a
> RST-to-docbook converter (shouldn't be that hard) and we need some
> formating rules (not very hard either, pretty much everyone knows how
> manpages look).

The docbook stuff has also some advantages, it can be checked against a stylesheet to see if the document is well formed, it really easy be convert into different outputs, like HTML, PDF, man-pages and so on..

Cheers,

Henning
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sip-router.org/pipermail/sr-dev/attachments/20090421/4d070aae/attachment.htm