On Mon, May 23, 2011 at 9:34 PM, Lex Trotman elextr@gmail.com wrote:
Is anyone open to idea of switching to AsciiDoc markup and set of tools? It can definitely output plain text, HTML and PDF, with and without Table Of Contents.
If there are no loud objections I'll put together samples of the newsletter's source file in AsciiDoc markup converted into plain text, HTML and PDF output formats.
Well, I'm biased of course.
OTOH if the Rest tools are too fragile it isn't worth sticking to them so I guess any options are open. In fact IIUC Python itself has now moved to a new toolset called sphinx, don't know any more though.
Asciidoc might be worth the example if you've got time since John already has a markdown example.
Sphinx utilizes reST and the docutils tools under the covers. BTW, all the [official Python docs] are written in reST and processed using [Sphinx].
[official Python docs]: http://docs.python.org/ [Sphinx]: http://sphinx.pocoo.org/
Asciidoc seems to have a pretty nice default html output style (looks like [git uses it] for some of their docs). Sphinx has [some themes] available. With Pandoc, you'd have to come up with some basic styling of your own.
[git uses it]: http://www.kernel.org/pub/software/scm/git/docs/everyday.html [some themes]: http://sphinx.pocoo.org/theming.html
These days, I find Markdown (with the Pandoc enhancements) to be the nicest looking and easiest to use markup of everything I've seen (ex., reST, moin-style, Textile, asciidoc, not to mention Perl Pod, LaTeX, Texinfo, and others). IMO, the easier it is to write and read as plain text, the less trouble you'll have finding people to write and update content, and the more you yourself will enjoy writing.
---John