[LLVMdev] Using ReST for documentation

[Mikhail Glushenkov]

[Chris asked me to bring this up on the mailing list some time
ago, but I couldn't get to it. Sorry for that.]

Since the beginning, I used ReST [1] for documenting llvmc, instead of
plain HTML that was used historically. In my opinion, ReST is much
easier to write and read (in the text editor or on terminal); it can
also be used to produce PDFs, man pages or HTML that looks exactly the
same as the rest of LLVM documentation (see [2] for example). However,
there are benefits in having a standardized procedure.

I propose that we allow using ReST (or some other lightweight markup
language that the majority agrees upon) for new documentation on the
grounds that this doesn't add too much overhead (generated HTML is
already used for man pages, for example). 

Since it is better to use a single format for documentation, the rest
of the docs should probably be also converted in the long term.



[1] http://docutils.sourceforge.net/rst.html

[2] http://llvm.org/docs/CompilerDriver.html 
(Note: this document is out of date; I've updated the style sheet since
then.)