[off-topic] [discussion] asciidoc vs nim-markdown

[Timothee Cour]

Didn't want to discuss this in #10 to keep each topic distinct; feel free to close if this is too off-topic :), but it may be worth discussing this at least once

Note also that @dom96 mentioned here that asciidoc could be another option for Nim documentation

while I do like asciidoc, the main argument I see against it is that markdown is far more ubiquitous and developpers are more likely to know it and be familiar with it, and it's not clear asciidoc's advantages outweigh this aspect.

since you're authoring nim-markdown maybe you have some insight/opinion on nim-markdown vs asciidoc (and @dom96 feel free to comment too)

Here are some readings I did:

advantages of asciidoc

• https://asciidoctor.org/docs/asciidoc-vs-markdown/

  • what truly makes AsciiDoc the right investment is that its syntax was designed to be extended as a core feature

  • AsciiDoc uses a consistent formatting scheme (i.e., it has consistent patterns).

  • builtin Includes syntax include::intro.adoc[] (but see #9)

  • AsciiDoc offers power and flexibility without requiring the use of HTML or “flavors” for essential syntax such as tables, description lists, admonitions (tips, notes, warnings, etc.) and table of contents.

  • Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.

  • AsciiDoc syntax was explicitly designed with the needs of publishing in mind, both print and web

• https://medium.com/the-bower/markdown-considered-harmful-495ccfe24a52

• https://www.red-gate.com/simple-talk/blogs/sundown-on-markdown/

advantages of markdown

• the point I raised above about familiarity / popularity

• https://news.ycombinator.com/item?id=9206755

AsciiDoc is a nice project, but I think that pandoc's variant of Markdown has a lot of advantages over AsciiDoc for academic writing [...]

[Dominik Picheta]

I wrote my book using AsciiDoc so I am pretty intimately familiar with it. So here is my opinion :)

For the forum Markdown is better.

For Nim documentation (if we were to change from rst to something else, and that's still a point of contention) it gets harder, AsciiDoc would possibly be better (AsciiDoc does have some odd quirks here and there though, like for example not being able to write "C++" because it's ambiguous with some AsciiDoc construct) but I would need to comprehensively compare rST/Markdown/AsciiDoc to really have a definitive answer. Honestly I think that rST is fine for Nim's docs and I'm not sure why you want to change it.

[Ju]

For the forum Markdown is better.

I would make nim-markdown gfm test case 100% passed in the next few days. I'd love to see nim-markdown being used in the forum! Let me know if there is any issue! 🎉

For Nim documentation, AsciiDoc would possibly be better.

I don't want to contribute any bias to the argument of which one is better since it's about people's taste. Asciidoc is the least markup language I used. But I'm pretty sure both rST and Markdown have proven their stability and extendability as document formats, for example, rST for Python and Markdown for Ruby.

If I were the designer of a language, I would go for Markdown as the default doc format probably. It's not because I like it (I actually like it), but the markdown has the most popularity nowadays comparing to the other doc formats. Using something that most people get used to makes developers' life just easier. See the Google trends: markdown 90+ v/s asciidoc 1 v/s rst 1. https://trends.google.com/trends/explore?geo=US&q=markdown,asciidoc,reStructuredText

Regardless of my opinion, I think the discussion will lead to an answer in Nim/9291. Close this issue since no more work is required in nim-markdown. :) Let me know if you have issues. Thanks!