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