Trent W. Buck wrote: > My strong personal preference is for reST, because it has a relatively > pleasant source markup, is relatively featureful for a lightweight > markup language, has a --strict mode, and generates pretty good HTML > and > (with the new rst2pdf) PDF output. I'm still concerned with its > scalability (document class "book" instead of "article"), but there's a > recent spin-off called Sphinx which might address that. > > References: > > http://docutils.sf.net/ > http://code.google.com/p/rst2pdf/ > http://sphinx.pocoo.org/ > > This would also give coloured code snippets, which some people might > conceivably care about.
This gets a big +1 from me. I've been using reStructuredText for a while now (most of the blog posts on my website are written in reST, particularly when I post about darcs actually), but some of my enthusiasm for it comes from the number of Python projects I work on, so I'm not sure how much interest there is here. First of all, Sphinx is awesome. If you haven't seen my work in progress documentation for "Darcsforge", it's built with Sphinx: http://repos.worldmaker.net/darcsforge/main/docs/.build/html/index.html For every page there you can click "View Source" on the side-bar and see the reStructuredText source of the page (which I think generally works well as readable "ASCII" when unformatted). Sphinx generates Tables of Contents and all of the navigation and indices, including the "quick search". Sphinx uses Pygments for syntax highlighting (and I've contributed a lexer for parsing Darcs patches, by the way). Sphinx creates a simple make file and generating output is as simple as "make html" or "make pdf" (also support for Windows HTML Help for a more "native" documentation experience in Windows) in the documents directory. Here's a couple more (close-to-hand) examples of Sphinx-based documentation: http://docs.djangoproject.com/en/dev/ http://docs.python.org/ Here's a .pdf set from the Python documentation, which I think looks great: http://docs.python.org/ftp/python/doc/current/python-docs-pdf-letter.zip Finally, here's a great general resource on reStructuredText: http://rst2a.com/ It's an "evangelism" website with tools that let you play with reStructuredText formatting and offer some gentle Quick Start learning tools. -- --Max Battcher-- http://worldmaker.net _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
