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 <levipear...@gmail.com> Date: Sat, Oct 18, 2014 at 6:50 PM Subject: ASCIIDoc Grammar To: carter.schonw...@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.
_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
