Out of curiosity I've looked up "asciidoc tutorial".
10% into the first page and I see this:
A [.myrole]#custom role# must be fulfilled by the theme.
Wait, is this in example 7 of 97? That's already... disturbing?
But I scroll just a little down and I see examples 11 and 12:
https://chat.asciidoc.org[Discuss AsciiDoc,role=external,window=_blank]
CAUTION If the link text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes.
link:++https://example.org/?q=[a b]++[URL with special characters]
> In Markdown, you sometimes have to put a backslash before special characters.
I think I get it now. Yes, I agree that sometimes-rules for escaping is bad. Should have to require escaping metacharacters all the time, not just in certain contexts.
I was talking about quoting or grouping things. Either require things like quotes for certain constructs all the time (no matter the content) or don’t.
Not in my opinion. How often does this actually come up in technical writing? I'm happy with one or two ugly edge cases if it means that the overall experience is nice: that's a perfectly fine tradeoff to me.
Like any good compression algorithm, asciidoctor optimizes for the common cases at the expense of the uncommon cases. For 98% of text you write, asciidoctor is probably much simpler than HTML
These are features that don't exist in Markdown though, unless there's some implementation that adds these. Also, the context of the parent comment and this post is documentation.
So, is it worse than HTML? Maybe, if you need those features often, but not for documentation where you'll rarely, if ever, use those.
At least an originally designed markdown falls back to HTML when it doesn’t directly support a particular feature. With Pandoc, markdown can fall back to LaTeX as well.
You can do the same in Asciidoc with the passthrough feature, either as an inline passthrough or a passthrough block. Granted, it's not syntax-less like Markdown, but it's there if you need it.
Inline example:
pass:[<u>underlined</u>]
or
+++<u>underlined</u>+++
10% into the first page and I see this:
Wait, is this in example 7 of 97? That's already... disturbing?But I scroll just a little down and I see examples 11 and 12:
Isn't this literally worse than HTML?