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