[SR-Dev] Module Documentation

[Martin Hoffmann]

Jan Janak wrote:
> 
> But if our goal is to produce plain text READMEs, wouldn't it make more sense
> to adopt something simpler, for example the dokuwiki format? It is easily
> readable as plain-text and we can edit it in the wiki and synchornize with
> READMEs in the repository.

This sort of leads to the lightweight markup approach. Basically, add a
small amount of markup and formatting rules to the README so that you
can turn them into a man page, PDF, Wiki pages, you name it.

The Python people use RST everywhere -- the entire documentation
basically is RST files (on docs.python.org you can even check the raw
files). While I am personally not too fond of RST, it would be a good
choice since obviously processing the stuff in Python is easy.

If we then define the required sections in the README file, we can write
a little script for turning it into nroff or docbook or whatever.

Regards,
Martin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
Url : http://lists.sip-router.org/pipermail/sr-dev/attachments/20090421/61146d52/attachment.pgp