4 ms·

Mind explaining how this is superior to Markdown?

by j0e1 8y ago

gouggoug 8y ago
Asciidoc has many more feature and as easy to use as Markdown. Markdown definitely does the job for very quick documentation, but when it comes to more in depth documentation I've found asciidoc to be much better. I'll use an example: I often need to create "Warning Notes" (aka "Admonitions") in my documentation. Those notes need to stand out, but they also need to not break the flow of reading. I need them to be visible, but easy to spot with the eye and ignore. It makes reading the doc and ignoring less important information easier. With Markdown, I can't create those notes. Other interesting and useful thing is the ability to use variables. This allows me to make the documentation dynamic. Imagine, for example, a documentation that has many CURL requests examples that must include an X-Auth-Token. I can dynamically generate the documentation with the Auth-Token of the user reading the doc, allowing them to Copy/Paste the examples without having to modify them first.
- chubot 8y ago
  FWIW, I use a macro processor with markdown. Markdown supports arbitrary inline HTML, which makes it very convenient to use like this. You can create a macro for the warning box. I have another one to insert not just code snippets, but the result of running the code snippet. I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.
  - mmsimanga 8y ago
    Can you please elaborate on how exactly you create the macros? I started using asciidoc because I could not find a neat way of embedding code snippets (stored in separate file) into markdown text. Asciidoc has this as built in feature.
    - peteretep 8y ago
      I'm not suggesting this as the right solution, but I wrote a lot of assignments for my MSc with Markdown + build scripts + a heavy amount of Perl. Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL. I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.
    - mkobit 8y ago
      This is one of my favorite features, too. I've found it works amazing when you generate the documentation or render it locally. Unfortunately, it doesn't work in "safe" mode sites like GitHub or GitLab where having a lightweight include feature for samples or tests would be useful. For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.
    - chubot 8y ago
      I wrote a script which preprocesses the .md file, passes certain sections to shell scripts, and inserts the result of the script back into the .md file. It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc. I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you. The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others. How does asciidoc do it? [1] http://www.oilshell.org/blog/ http://www.oilshell.org/blog/ [2] https://github.com/oilshell/blog-code/tree/master/tools-snapshot https://github.com/oilshell/blog-code/tree/master/tools-snap... [3] http://www.oilshell.org/blog/2018/02/14.htm http://www.oilshell.org/blog/2018/02/14.htm
hnruss 8y ago
Here's a comparison: https://asciidoctor.org/docs/asciidoc-vs-markdown/ https://asciidoctor.org/docs/asciidoc-vs-markdown/ (Note: This appears to be written by the AsciiDoc team)
ktosobcy 8y ago
For me - ability to structure documents nicely with `include::`

Mind explaining how this is superior to Markdown?

by j0e1 8y ago

Mind explaining how this is superior to Markdown?

Asciidoc has many more feature and as easy to use as Markdown. Markdown definitely does the job for very quick documentation, but when it comes to more in depth documentation I've found asciidoc to be much better. I'll use an example: I often need to create "Warning Notes" (aka "Admonitions") in my documentation. Those notes need to stand out, but they also need to not break the flow of reading. I need them to be visible, but easy to spot with the eye and ignore. It makes reading the doc and ignoring less important information easier. With Markdown, I can't create those notes. Other interesting and useful thing is the ability to use variables. This allows me to make the documentation dynamic. Imagine, for example, a documentation that has many CURL requests examples that must include an X-Auth-Token. I can dynamically generate the documentation with the Auth-Token of the user reading the doc, allowing them to Copy/Paste the examples without having to modify them first.

chubot 8y ago
FWIW, I use a macro processor with markdown. Markdown supports arbitrary inline HTML, which makes it very convenient to use like this. You can create a macro for the warning box. I have another one to insert not just code snippets, but the result of running the code snippet. I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.
- mmsimanga 8y ago
  Can you please elaborate on how exactly you create the macros? I started using asciidoc because I could not find a neat way of embedding code snippets (stored in separate file) into markdown text. Asciidoc has this as built in feature.
  - peteretep 8y ago
    I'm not suggesting this as the right solution, but I wrote a lot of assignments for my MSc with Markdown + build scripts + a heavy amount of Perl. Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL. I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.
  - mkobit 8y ago
    This is one of my favorite features, too. I've found it works amazing when you generate the documentation or render it locally. Unfortunately, it doesn't work in "safe" mode sites like GitHub or GitLab where having a lightweight include feature for samples or tests would be useful. For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.
  - chubot 8y ago
    I wrote a script which preprocesses the .md file, passes certain sections to shell scripts, and inserts the result of the script back into the .md file. It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc. I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you. The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others. How does asciidoc do it? [1] http://www.oilshell.org/blog/ http://www.oilshell.org/blog/ [2] https://github.com/oilshell/blog-code/tree/master/tools-snapshot https://github.com/oilshell/blog-code/tree/master/tools-snap... [3] http://www.oilshell.org/blog/2018/02/14.htm http://www.oilshell.org/blog/2018/02/14.htm

hnruss 8y ago

Here's a comparison: https://asciidoctor.org/docs/asciidoc-vs-markdown/ https://asciidoctor.org/docs/asciidoc-vs-markdown/ (Note: This appears to be written by the AsciiDoc team)

ktosobcy 8y ago

For me - ability to structure documents nicely with `include::`