21 Apr
2009
21 Apr
'09
11:47 a.m.
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