[LLVMdev] Using ReST for documentation

[Tanya Lattner]

Can you compare ReST to docbook? We've talked about using docbook for  
a long time. What are the pros and cons of each?

Thanks,
Tanya

On Dec 9, 2008, at 7:56 AM, Mikhail Glushenkov wrote:

> [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.)
>
>
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev