21 Apr
2009
21 Apr
'09
10:09 a.m.
Juha Heinanen wrote:
Klaus Darilion writes:
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.
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. 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).
Regards,
Martin
[0] The git Web frontend's URL scheme sucks big time, but here is an
example:
http://git.sip-router.org/cgi-bin/gitweb.cgi?p=ser_modules;a=blob;f=modules…
We didn't check in the results, but here is how it looks like:
http://partim.de/pub/misc/auth.7
I prefer README as authoritative source - every
feature commit should
also add a feature descrption (e.g. do not write long commit messages
but write the text into the README and then copy paste it into the
commit message)
i agree and also, there should be a common format for readme file source
files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc
api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc
auth_radius_admin.xml auth_radius.xml