# Asciidoc Open Specification

**URL:** <https://talk.commonmark.org/t/asciidoc-open-specification/3039>\
**Category:** Meta\
**Created:** [January 8, 2019, 2:02pm UTC](https://talk.commonmark.org/t/asciidoc-open-specification/3039 "2019-01-08T14:02:27Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![Crissov](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/crissov/32/1455_2.png) [@Crissov](https://talk.commonmark.org/u/Crissov)\
**Post date:** [January 8, 2019, 2:02pm UTC](https://talk.commonmark.org/t/asciidoc-open-specification/3039/1 "2019-01-08T14:02:27Z")

</div>

Apparently, [Asciidoc](https://asciidoctor.org/news/2019/01/07/asciidoc-spec-proposal/) is getting an open specification under the umbrella of the Eclipse Foundation.

It always had some features by default that Markdown only has in (often diverging) extended flavors, also some design choices (e.g. intraword emphasis) are better than in Commonmark (mostly for legacy reasons), but I really dislike how Asciidoc relies on English keywords for some key features like links.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [January 8, 2019, 8:13pm UTC](https://talk.commonmark.org/t/asciidoc-open-specification/3039/2 "2019-01-08T20:13:36Z")

</div>

Asciidoc is nice in many ways. But it prioritizes parsing simplicity over readability; for an illustration see the example in section 1.1 of the Commonmark spec.

I wish them luck on the spec. I suspect it will be a much easier project than for Commonmark.

---

<div class="post-metadata">

**Author:** ![jgm](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/jgm/32/1360_2.png) [@jgm](https://talk.commonmark.org/u/jgm)\
**Post date:** [January 9, 2019, 5:06pm UTC](https://talk.commonmark.org/t/asciidoc-open-specification/3039/3 "2019-01-09T17:06:46Z")

</div>

Asciidoc has some pretty rough edges.

> <https://github.com/jgm/pandoc/issues/2337#issuecomment-452771806>
>
> Pandoc version 1.15.0.6 doesn't correctly escape \`asciidoc\` output
> 
> \`\`\`
> $ echo '…\<a href="http://example.com"\>\]\[\</a\>' | pandoc -f html -t asciidoc
> http://example.com\[\]\[\]
> \`\`\`
> 
> which asciidoc would render back as ...
> 
> \`\`\`
> $ echo '\<a href="http://example.com"\>\]\[\</a\>' | pandoc -f html -t asciidoc|asciidoc - |grep example\\.com
> \<div class="paragraph"\>\<p\>\<a href="http://example.com"\>http://example.com\</a\>\[\]\</p\>\</div\>
> \`\`\`
> 
> Unfortunately, the rules for escaping asciidoc special chars are complex and I cannot point to a single place in the asciidoc documentation. The general rule is that the '\\' character is used to escape. So with correct quoting/escaping ...
> 
> \`\`\`
> $ echo '\<a href="http://example.com"\>\\\]\[\</a\>' | pandoc -f html -t asciidoc|asciidoc - |grep example\\.com
> \<div class="paragraph"\>\<p\>\<a href="http://example.com"\>\]\[\</a\>\</p\>\</div\>
> \`\`\`
> 
> \*\*References\*\*
> \- http://www.methods.co.nz/asciidoc/userguide.html#X51
> \- http://www.methods.co.nz/asciidoc/faq.html#\_how\_can\_i\_escape\_asciidoc\_markup
> \- http://www.methods.co.nz/asciidoc/faq.html#\_some\_elements\_can\_8217\_t\_be\_escaped\_with\_a\_single\_backslash (\_weird\_ cases!)
> \- http://www.methods.co.nz/asciidoc/faq.html#\_how\_can\_i\_escape\_a\_list
> \- https://github.com/jgm/pandoc/issues/2334