[Geany] Geany Newsletter Vol. 2

Lex Trotman elextr at xxxxx
Tue May 24 04:38:53 UTC 2011


Hi John,

Let me declare at the outset that I have contributed a few minor
patches to Asciidoc and respond to some mailing list queries and I am
using it within a Python project, so I am not an unbiased observer.
:-)

>
> 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/

Yes, thats where I saw it but didn't investigate further

> [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

Yes, and see also http://www.methods.co.nz/asciidoc/index.html#X6

That list includes whole books, in fact Asciidoc is one of the formats
O'Reilly (you know, publishers of slim volumes on computing topics)
accepts.

Git, Waf, Pacman, Cherokee are some users that list members might know
about.  Asciidoc was designed for documents, not extracting docstrings
from code so the focus and toolset is different.  The newsletter is a
document not code.

> [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.

And of course I say all that about Asciidoc markup :-).

In the end there isn't that much in the source formats of all the
lightweight markup languages, it comes to personal taste.  I just wish
there were more converters, the concepts are mostly the same but the
syntaxes always differ in details.  And hand conversion is a pain.

The thing that differentiates for me is documentation and tools.

Asciidoc is reasonably well documented, many queries get answers
including pointers to the manual.  I got turned off markdown when the
website displayed as a 100mm strip down the centre of my widescreen
monitor, poor advertisement.

Since Asciidoc goes through docbook it has the benefit of two PDF
backends, dblatex and fop and all the well tested XSLT to generate
other XML forms, eg XHTML, HTML epub, manpages etc. and Asciidoc
provides the a2x wrapper that runs the whole chain rather than dumping
you with an intermediate file and leaving it all up to you.

And I happen to like the way its implemented as a parser driven by
config files and backends driven by config files all of which cascade
like CSS, so you only have to write the one line you want to change,
not copy the whole config file.

But as I am not likely to contribute a lot to the newsletter I won't
try to influence (much ;-) the guys who do.

Cheers
Lex



More information about the Users mailing list