4 ms·
Don't want to be a troll, but if you are writing anything that is not a README and/or is a book or booklet or bookish, do yourself a favor and use Asciidoc inst
by kimi 5y ago
Don't want to be a troll, but if you are writing anything that is not a README and/or is a book or booklet or bookish, do yourself a favor and use Asciidoc instead.
- jtbayly 5y agoGive me a reason to use asciidoc rather than bookdown.
- gexla 5y agoI assume the person you're replying to was referring to Markdown rather than Bookdown. It seems that Asciidoc was designed for the direction which Markdown has going with all these variants. If you find yourself chasing these Markdown variants to get more flexibility, then Asciidoc might be what you're looking for. I don't know anything about Bookdown and it may be similar to Asciidoc. I would be willing to bet that Asciidoc would be around longer than most of the MD variants though. Why might you want to continue using MD flavors? You already have loads of MD docs and you have no control over the processes which create them (shared environment, higher-ups force you to use MD, etc.) NOTE: If you're interested in Asciidoc, also take a look at Asciidoctor.
- jtbayly 5y agoThanks. That's basically what I figured. One feature I wanted that made me go with bookdown is that the static website it creates has search builtin.
- debiandev 5y agoThis! Asciidoc is the grown-up brother of Markdown. Designed to scale up to entire books, handle images, tables, references, citation, book indexes, maths. And the syntax is very friendly and intuitive.
- kimi 5y agoAnd it's quite easy to insert compiled images, e.g. Graphviz, UML diagrams, Ditaa, just by having the SOURCE in your document.
- davegauer 5y agoAbsolutely. AsciiDoc (2002) is actually 2 years older than Markdown (2004), but is surprisingly similar to write. It was created as an equivalent to DocBook XML for the creation of book-length technical documents. It has a rich history and is well supported in many places (try writing a README.adoc for your next GitHub-hosted repo). It is also currently undergoing a standardization process: https://projects.eclipse.org/proposals/asciidoc-language https://projects.eclipse.org/proposals/asciidoc-language
- dredmorbius 5y agoWhat's your suggested Asciidoc toolchain? (Pandoc will ingest Asciidoc as well as Markdown, FWIW.)
- kimi 5y agoAt work, we have been using Asciisoc for 10 years or so, so we use Asciidoc -> XSLT -> PDF / chunked HTML. Works great, not nice to use. For new projects, we use Asciidoctor - it does everything but chunked HTML, and it's a pleasure to use.
- dredmorbius 5y agoThanks.