Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] Intro + History of Markup Languages

Hi Dan,

Thank you for sharing a little bit about yourself and about your experiences transitioning documentation to AsciiDoc. It's interesting to see that our path to AsciiDoc was so similar.

I agree that there is plenty of room for the AsciiDoc ecosystem to grow, and, in my opinion, that's going to make this standardization effort thought-provoking and exciting. The AsciiDoc WG will finally give us the space to discuss and address the broader issues in the ecosystem such as the demands of different output formats, changing reader expectations, and expanding semantics. Speaking specifically to one of your thoughts, a goal of this effort is to parse and process AsciiDoc independent of language runtime. In that sense, there's no official language to target. Though a WebAssembly implementation would certainly have great utility.

Like you, I'm also looking forward to many constructive discussions about how to take AsciiDoc further.

Best regards,


On Fri, Feb 14, 2020 at 4:54 AM Daniel Mulholland <dan.mulholland@xxxxxxxxx> wrote:

Just a little ice breaker from me.

First, I really appreciate OpenDevise stepping forward to start this specification process and I'm grateful for the shepherding of the Eclipse Foundation. Thanks for making it easy for individuals to be a part of this and recognising the benefits of a formal process.

While many Asciidoc users seem to be coming from a software development perspective I'm a professional engineer (even worse, a manager of engineers...). I work in an electricity transmission company and my team (and especially myself) have been reasonably heavy users of Asciidoc (and Asciidoctor) for the past 4-5 years. We've migrated several thousand pages (the type you look at with your eyes) of engineering documentation and in-house standards from Microsoft Word to Asciidoc. Key reasons for that include:

* format stability (older Microsoft Word documents combust easily or can no longer be opened due to enterprise security restrictions)
* ability to use version control / git
* having a "properly architected format" (unlike Markdown) where there is a set of semantics mapping onto user requirements (via Docbook) for things like a bibliography, footnotes, appendixes etc.
* Ability to use CI/automation in publishing, proofing, format conversion etc.
* Ongoing development and a constructive community

Over the years I've looked into transitioning documentation to LaTeX, Markdown, RST, wikitext (and looked into using Docbook) and never felt I had found a lightweight answer for technical documentation until I cam across Asciidoc.

I can see there's plenty of room for the ecosystem to grow and address syntax issues, multi-"page"  documents, different output formats and different implementation languages but I'm delighted that this standardization process has started and we can work through that.

I found the presentation "A brief history of markup languages" by Tony Ibbs to be useful context around various Markup languages and thought others might be interested. See:

I think Asciidoc has weathered well given its age. One question I ask myself is, "What are the key developments over the last 15 years which we need to recognise in the standards effort?". I'm interested in the thoughts of others...

Off the top of my head:

* Separating form vs. content vs. presentation has been wildly successful.
* The importance of exposing and documenting a DOM structure
* Thinking through parsing at the same time as syntax development/proposed changes so parsing can be coded efficiently
* Perhaps a target for an "official" Asciidoc implementation should be WebAssembly?

Looking forward to the discussions.

best regards


Private or confidential message? Public Key available here: 

asciidoc-wg mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

Sarah White
OpenDevise |
sarah@xxxxxxxxxxxxxx | @carbonfray

Back to the top