3 ms·

Yeah, Markdown's not really a print document format. But LMLs (lightweight markup) don't begin and end with Markdown. Asciidoc, on the other hand . . I've writ

Yeah, Markdown's not really a print document format. But LMLs (lightweight markup) don't begin and end with Markdown. Asciidoc, on the other hand . . I've written aircrew flight checklists, component maintenance manuals, typescript developer documentation, illustrated parts catalogues, maintenance handbooks, operation guides, and a good-old-fashioned novelette in Asciidoc. Last few years with VSC. It's fast as hell. I got Asciidoc include for re-use, I got Asciidoc conditionals, VSC snippets, I got a billion other toys like textql, diagrams, wireviz. And yeah yeah yeah, I know, it's cheating: Asciidoc is DocBook, DocBook is XML. Except Asciidoc's not XML. Asciidoc renders in Chrome/Firefox/Edge extensions, Ruby, JS, Python, and it exports to DocBook, LaTeX, PDF, HTML5, ePub, MOBI, MSO via DocToolChain or Pckr and, well, hell, bring in Pandoc if you want something else. When it comes to the Asciidoc tools, I can go from bare metal to full-up publishing environment in ten minutes. And how do I render DocBook again? Oh, the XML pipelines. Those pipelines. Schemas breaking XML spec[1], "XML-aware" diff/merge, whitespace[2], sneaky goddamn proprietary entities[3], namespaces, 1NF, computability[4], charset, semantic-less, hierarchy fetishism, etc etc etc blabbity blabbity blah. I just realized this post sounds really frickin' angry, and I want to take a line here to say that I love all ya'll, but XML publishing has left some scars, and I'm sorry about that. [1] "Leading whitespace in attributes? CHARMING" [2] No such thing as "officially normalized" when it comes to XML whitespace, which means no lines, no tabs, no spaces. [3] Goddamn REVBARS [4] Ah, infinite arbitrary nesting, what a perfect fit for natural language

bobbylarrybobby 3y ago
+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
Also, in case it matters to anyone: IJ plugin! https://plugins.jetbrains.com/plugin/7391-asciidoc https://plugins.jetbrains.com/plugin/7391-asciidoc (Apache 2: https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/0.39.2/LICENSE https://github.com/asciidoctor/asciidoctor-intellij-plugin/b... )

bobbylarrybobby 3y ago

+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

Also, in case it matters to anyone: IJ plugin! https://plugins.jetbrains.com/plugin/7391-asciidoc https://plugins.jetbrains.com/plugin/7391-asciidoc (Apache 2: https://github.com/asciidoctor/asciidoctor-intellij-plugin/blob/0.39.2/LICENSE https://github.com/asciidoctor/asciidoctor-intellij-plugin/b... )