4 ms·

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. Wai

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] Isn't this literally worse than HTML?

keybored 4y ago
Having to use quotes (or any other symbol) sometimes based on learned rules is a big no-no for lightweight markup in my book.
- xigoi 4y ago
  In Markdown, you sometimes have to put a backslash before special characters.
  - keybored 4y ago
    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.
  - keybored 4y ago
    > 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.
nerdponx 4y ago
What tutorial? The official docs are well-written and rightly don't show advanced features at the beginning: https://docs.asciidoctor.org/asciidoc/latest/document-structure/ https://docs.asciidoctor.org/asciidoc/latest/document-struct... > Isn't this literally worse than HTML? 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.
nvrspyx 4y ago
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.
- jonhohle 4y ago
 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.
 - nvrspyx 4y ago
 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:[underlined] or +++underlined+++
bobbylarrybobby 4y ago
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

keybored 4y ago

Having to use quotes (or any other symbol) sometimes based on learned rules is a big no-no for lightweight markup in my book.

xigoi 4y ago
In Markdown, you sometimes have to put a backslash before special characters.
- keybored 4y ago
  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.
- keybored 4y ago
  > 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.

nerdponx 4y ago

What tutorial? The official docs are well-written and rightly don't show advanced features at the beginning: https://docs.asciidoctor.org/asciidoc/latest/document-structure/ https://docs.asciidoctor.org/asciidoc/latest/document-struct... > Isn't this literally worse than HTML? 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.

nvrspyx 4y ago

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.

jonhohle 4y ago
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.
- nvrspyx 4y ago
 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:[underlined] or +++underlined+++

bobbylarrybobby 4y ago

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