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