Levi, thanks for sharing this!
@herbert and austin, how much should we care about the doc format
being easy to reparse?
---------- Forwarded message ----------
From: Levi Pearson
Date: Sat, Oct 18, 2014 at 6:50 PM
Subject: ASCIIDoc Grammar
To: carter.schonwald@gmail.com
I saw your question in the ghc-devs archive about asciidoc, and I
figured I'd reply out-of-band since I don't subscribe to ghc-devs.
Feel free to forward it there if you think it'd be useful.
I have looked pretty deeply into the implementation of the canonical
asciidoc as well as asciidoctor, which is a re-implementation in Ruby
and which serves as the translator for github. There's no formal
grammar, and it would be difficult to construct one, as it's not
actually a fixed format.
The asciidoc engine is actually a macro-processing engine that's
designed to translate both in-line patterns and block-style patterns
based on delimiters and attributes. It's driven to a large extent by a
set of configuration files that define a lot of macros in a fairly
general way, with just a couple of special-purpose parsing mechanisms.
The macros can all be parameterized by "attributes" that can have
default values, and this allows you to inject semantic tags or create
new inline or block patterns that essentially expand to lower-level
inlines/blocks with specific attributes. The back-ends can also use
attributes to select how spans and blocks are rendered.
It's a very flexible system, and lines up pretty well with the
semantics of DocBook and XML in general. Its main advantage over
something like Markdown (and it can actually be reconfigured to be
very Markdown-like simply by changing regular expressions in the
config files) is that it allows you to add semantic markup and
higher-level document structure that's specific to your documentation
project without having to touch the main engine code. That's an
especially good thing as it's a bit messy and hard-to-follow.
