I much prefer Asciidoctor to Markdown when writing documents that's longer than a single A4 page, since it has the ability to combine multiple files into a single document if needed.
Compare AsciiDoc and Markdown
41–50 of 137 posts
Re: Compare AsciiDoc and Markdown
#42“it also fulfills the objective of ensuring your content is maximally reusable”
This is a bit of a trap when it comes to teams chasing the goal of modular documentation.
AsciiDoc let’s you include other AsciiDoc files, so teams modularize content with the idea that all these modules are potentially reusable.
But unlike code which, say, might use a method that is available bc another file has been included/imported, an AsciiDoc include doesn’t reveal any of its content. It’s just a file name that will be replaced with the content of that file upon render.
This means you literally cannot read modularized content from source - you need to open up every included file and read each out of context.
Available tooling also presents previewed/rendered includes as if they are part of the parent document, which removes the ability to identify modularized content from the output.
In my experience this results in documentation that is modularized by diktat - usually after being authored in a Google Doc. Reuse never happens, in fact nobody but the author really knows what content was modularized in the first place.
Re: Compare AsciiDoc and Markdown
#43Markdown's single best idea is that it is very readable "raw". While AsciiDoc is better than, say, html, it seems that's mostly a lucky accident because it's close to Markdown. Where it diverges, it looks like it fell from the XML tree. Example: .Lightweight Markup NO THIS TEXT IS NOT LIGHT Now, in fairness, Markdown doesn't have any methods to do that. But for quotes, Markdown gets it right: > this is a quote > and…
If I remember it correctly the origin story is „Docbook as non-XML syntax“, so it really fell from the XML tree.
Re: Compare AsciiDoc and Markdown
#44I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…
RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain as web applications of it will commonly go for, where any indentation must be applied manually by the writer. So I’d say it’d be good to get a new syntax construct for fenced, rather than indented, directives. For example, this is what reStructuredText has:
.. directive-name:: first-line-options
:subsequent-options: and their values
:and-more: if you want
Then the directive’s body.
```directive-name:: first-line-options
:subsequent-options: and their values
:and-more: if you want
Then the directive’s body.
```
As it stands, reStructuredText is based around having visually-pretty source: monospacedly-aligned tables, indentation for hierarchy, that sort of thing. (Headings feel like the only major thing that doesn’t use very significant whitespace.) I almost always like this, but there are definitely some situations when it’d be nice not to work that way.
Would you go all-in on fenced things rather than indented things? I dunno. Probably.
Re: Compare AsciiDoc and Markdown
#45Earlier quoted context omitted.
It's been a bit of a disappointment for me to discover that AsciiDoc's grammar is so complex that they didn't even describe it in a spec. Their spec is a collection of tests. This must be contributing a lot to the adoption difficulty (at least for resource-limited open-source projects). There's a good chance you will not find an AsciiDoc parser library for your favourite programming language.
There is one for go which is my favorite language. And there is also one for python and javascript. Did you check ?
If you mean libasciidoc for Go, it does not support all the AsciiDoc features [1]. The JS parser is transpiled [2] from the Ruby implementation (which is not a bad thing, it's just something most languages can't have).
My favourites are Rust and Haskell. Neither of them had a parcer until recently (even though the original implementation has been around for a few years now). Both are at early development stages at the moment.
[1]: https://github.com/bytesparadise/libasciidoc/blob/master/LIM...
Re: Compare AsciiDoc and Markdown
#46The worst part of AsciiDoc I think is its name. It sounds so archaic.
It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents. I would like to imagine that in this day and age that isn't the case, but the name works against it.
Came here to say this. UTF-8/16 represents such a relief from the previous text-encoding nightmares that I run away from any tooling that does not use it.
If anyone else was a web dev in the 90s, you know what I’m talking about.
Re: Compare AsciiDoc and Markdown
#47Earlier quoted context omitted.
It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents. I would like to imagine that in this day and age that isn't the case, but the name works against it.
Particularly when the syntax bakes in things like support for converting certain ASCII sequences into Unicode characters [0] [0] https://docs.asciidoctor.org/asciidoc/latest/text/quotation-...
Yes, I finally got around to adding some "quail" stuff to my .emacs so that I can directly type various kinds of quotation mark and dash rather than rely on complex conversion rules that sometimes go wrong.
The lack of first-class support for balanced quotation marks seems to be a major problem for computers. I think a lot of computer code, particularly scripts, would be easier to read and less buggy if the languages had been designed by someone with balanced quotation marks on their keyboard.
As a thought experiment, imagine what Lisp would look like if '(' and ')' were the same character and you had to use the same work-arounds that shell scripts use for open quotation mark and close quotation mark being the same character. Instead of (a ((b c) d)) we'd write |a \|\\\|b c\\\| d\||. That's fine, right? We can live with that?
Perhaps we should think ourselves lucky that 0 and O are not the same character, and 1 and l, like they were on the first mechanical typewriters.
Mind you, there's one similar annoyance that predates typewriters and continues to plague us in Unicode: apostrophe and closing single quotation mark are logically quite different things, but they're the same character: ’
Re: Compare AsciiDoc and Markdown
#48I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…
RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
RestructuredText was chosen over Asciidoc for the Linux Kernel Documentation:
- https://lwn.net/Articles/692704/
- https://www.kernel.org/doc/html/latest/#other-documentation
There is a lot of comparison made in that decision.
Re: Compare AsciiDoc and Markdown
#49Markdown's single best idea is that it is very readable "raw". While AsciiDoc is better than, say, html, it seems that's mostly a lucky accident because it's close to Markdown. Where it diverges, it looks like it fell from the XML tree. Example: .Lightweight Markup NO THIS TEXT IS NOT LIGHT Now, in fairness, Markdown doesn't have any methods to do that. But for quotes, Markdown gets it right: > this is a quote > and…
If I remember it correctly the origin story is „Docbook as non-XML syntax“, so it really fell from the XML tree.
Actually, Docbook started as an SGML vocabulary and only in version 5 became XML-first. And SGML, as it relates to this thread, is a parser generator you can use to perform markdown-to-HTML conversion (including full HTML inlining), or AsciiDoc/rST or your own custom extension syntax to whatever XMLish angle-bracket markup you wish. So apologies, but considering we have SGML since 1986 or earlier, discussing surface syntax (markdown vs AsciiDoc vs rST vs orgmode or whatever) seems kindof moot and merely a matter of personal preference really.
Re: Compare AsciiDoc and Markdown
#50FreeBSD has recently switched from DocBook to AsciiDoc for its documentation: https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-pri... Markdown was also an option but it was missing too many features for a documentation set of this size.
That's actually a likely switch, since AsciiDoc was specifically designed to optimally support Docbook features. So that switch should be painless.