[Geany] Geany Newsletter Vol. 2

[John Gabriele]

On Mon, May 23, 2011 at 9:34 PM, Lex Trotman <elextr at 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