4 ms·

+1 asciidoc is where it's at. Given its strengths and similarity to markdown, I wonder why it hasn't taken off to the same extent.

mdaniel 3y ago
the most famous example I know of: https://docs.atlas.oreilly.com/writing_in_asciidoc.html https://docs.atlas.oreilly.com/writing_in_asciidoc.html
CJefferson 3y ago
Honestly, the first guide that comes up when you Google, asciidoctor, is bad. I just checked if it had improved and it starts talking about "If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.", without defining assigning, and before I've been told how to put in a header. I got annoyed around there and went back to markdown.
- MilStdJunkie 3y ago
  That's from the writer's guide, which sucks. I'd hit the official doc site here: https://docs.asciidoctor.org/asciidoc/latest/ https://docs.asciidoctor.org/asciidoc/latest/. They rejiggered the docs with Antora oh, eh, four or so years ago. But before I say anything else, if your use case is satisfied by Markdown, there's no reason to go anywhere else. Asciidoc's when you need more complex functionality: transclusion, conditionals, complex tables, weird print formats, ToC/LoT/LoF, indices, etc.
MilStdJunkie 3y ago
The main reason is that the processor was never JS-native. First Python, then Ruby, and then it got transpiled all over. Sure, today Asciidoctor.js is damn slick, but it took a while, and Opal.js has had some rough shakes. The second reason - and a close tie with above - is that features aren't free. *Asciidoc is more complex than Markdown*, no way around that. The fact that you can also monkey around with transclusion and conditionals doesn't help things either - you can really dig yourself into a hole with transclusion unless you plan things very very carefully. Digression: I want to expand on that point a moment. Document engineers have known that transclusion+conditionals were problematic functionality since 1994; it's why HTML never got transclusion as a core function, it breaks natural language documents. All the DITA/xinclude/"content re-use" people came from outside the initial technical GML/SGML group, and DITA architects were exclusively polisci/psych/pedagogical academics. There were some raised voices in the late 90s/early aughts, which we're still paying for to this day. Note that Antora - the Asciidoc build system - has an "opinionated" architecture, it's for this same reason: managing the complexity of transclusion. OK, digression over. The third reason is the name. All due respect, but "asciidoc" is kind of meaningless, they'd have been better off drawing a clearer line between Asciidoc and DocBook. Something like LiteBook, or DocDown. "Asciidoc" though, makes a connotation that the central feature is the text encoding, and that's not really a substantial selling point. Having that DocBook lineage is; that's like Return of the King kind of lineage, if Aragorn had been lost in the XML wilds and then returned to the old design philosophy of GondorML to marry a hot elf.

mdaniel 3y ago

the most famous example I know of: https://docs.atlas.oreilly.com/writing_in_asciidoc.html https://docs.atlas.oreilly.com/writing_in_asciidoc.html

CJefferson 3y ago

Honestly, the first guide that comes up when you Google, asciidoctor, is bad. I just checked if it had improved and it starts talking about "If you want to enable ad-hoc quotes substitution, then assign the macros value to subs and use the inline pass macro.", without defining assigning, and before I've been told how to put in a header. I got annoyed around there and went back to markdown.

MilStdJunkie 3y ago
That's from the writer's guide, which sucks. I'd hit the official doc site here: https://docs.asciidoctor.org/asciidoc/latest/ https://docs.asciidoctor.org/asciidoc/latest/. They rejiggered the docs with Antora oh, eh, four or so years ago. But before I say anything else, if your use case is satisfied by Markdown, there's no reason to go anywhere else. Asciidoc's when you need more complex functionality: transclusion, conditionals, complex tables, weird print formats, ToC/LoT/LoF, indices, etc.

MilStdJunkie 3y ago

The main reason is that the processor was never JS-native. First Python, then Ruby, and then it got transpiled all over. Sure, today Asciidoctor.js is damn slick, but it took a while, and Opal.js has had some rough shakes. The second reason - and a close tie with above - is that features aren't free. *Asciidoc is more complex than Markdown*, no way around that. The fact that you can also monkey around with transclusion and conditionals doesn't help things either - you can really dig yourself into a hole with transclusion unless you plan things very very carefully. Digression: I want to expand on that point a moment. Document engineers have known that transclusion+conditionals were problematic functionality since 1994; it's why HTML never got transclusion as a core function, it breaks natural language documents. All the DITA/xinclude/"content re-use" people came from outside the initial technical GML/SGML group, and DITA architects were exclusively polisci/psych/pedagogical academics. There were some raised voices in the late 90s/early aughts, which we're still paying for to this day. Note that Antora - the Asciidoc build system - has an "opinionated" architecture, it's for this same reason: managing the complexity of transclusion. OK, digression over. The third reason is the name. All due respect, but "asciidoc" is kind of meaningless, they'd have been better off drawing a clearer line between Asciidoc and DocBook. Something like LiteBook, or DocDown. "Asciidoc" though, makes a connotation that the central feature is the text encoding, and that's not really a substantial selling point. Having that DocBook lineage is; that's like Return of the King kind of lineage, if Aragorn had been lost in the XML wilds and then returned to the old design philosophy of GondorML to marry a hot elf.