<html><head><meta name="qrichtext" content="1" /></head><body style="font-size:9pt;font-family:Lucida Console">
<p>On Tuesday 21 April 2009, Martin Hoffmann wrote:</p>
<p><span style="color:#008000">> Before sip-router started, I started an effort for SER to have all</span></p>
<p><span style="color:#008000">> module documentation standardized into a manual page based on docbook</span></p>
<p><span style="color:#008000">> sources.[0] The result is certainly optimal, for a user on a *nix system,</span></p>
<p><span style="color:#008000">> doing "man tm" should be natural.</span></p>
<p></p>
<p>Hi Martin,</p>
<p></p>
<p>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.</p>
<p></p>
<p>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. </p>
<p></p>
<p><span style="color:#008000">> The source format is dubious, though. I eventually ended up with docbook</span></p>
<p><span style="color:#008000">> since it is a standard of sorts and there are tools to make manpages out</span></p>
<p><span style="color:#008000">> of the sources (although they need some tweaking). However, editing is</span></p>
<p><span style="color:#008000">> as painful as it gets.</span></p>
<p></p>
<p>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. </p>
<p></p>
<p><span style="color:#008000">> For documentation, painful editing usually means </span></p>
<p><span style="color:#008000">> it is not being done. So, if someone has a better suggestion for the </span></p>
<p><span style="color:#008000">> source format, they are most welcome. Some lightweight markup like RST</span></p>
<p><span style="color:#008000">> is probably a good idea, but then someone needs to write a</span></p>
<p><span style="color:#008000">> RST-to-docbook converter (shouldn't be that hard) and we need some</span></p>
<p><span style="color:#008000">> formating rules (not very hard either, pretty much everyone knows how</span></p>
<p><span style="color:#008000">> manpages look).</span></p>
<p></p>
<p>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..</p>
<p></p>
<p>Cheers,</p>
<p></p>
<p>Henning</p>
</body></html>