AsciiDoc was written primarily as a way to write DocBook without having to use XML. AsciiDoctor has an alternative goal of writing HTML without having to use HTML. The subtle differences between these goals leads to a lot of "gotchas" if you try to serve both of them at the same time. At least if AsciiDoc is only a consumable in your build system and you deliver the compiled artifacts (be it HTML, PDF, man pages, etc), you can probably be fine enough knowing what your implementation does and does not do.
but without support for includes. ;_;
It might not occur to people in North America that even British English users are inconvenienced when restricted to ASCII only (GBP vs £) and therefore the name implies that this tool is not for us.
Along with the notion of obsolescence one might derive from it, it's also not particularly sticky/memorable. It might sound silly but I think snappiness or lack thereof has an impact on rate of adoption, because for people to use things they have to first remember them.
<warning>
You _really_ shouldn’t
play with matches, Debbie.
</warning>
<style>
warning {
display: block;
color: red;
}
</style>
Relying on asciidoc for styling elements like admonitions always felt like the wrong tool for the job. Like writing a Java generator in Perl, instead of just writing actual Java.
Markdown itself comes (not even implicitly, but explicitly!) with the philosophy that there is no "true" standard. It's very flexible, very customizable, and does not aim for interop between implementations, for tooling, and so on.
Asciidoc tries to focus on being a Standard with a capital "S" so that the entire ecosystem around it can interop properly without implementation specific quirks/incompatibilities.
Both are good tools but with completely different philosophies. I learned all of this because I wanted to make a fast markdown parser in WASM directly. And at the same time I wanted to have a common way to put together a book to be published. What I learned quickly when trying to come at Markdown from a technical perspective is that there are dozens or more Markdown flavors and the idea of "Markdown" as a "general thing" isn't accurate, there's not even really a "core" shared between the variants/flavors. Which is in stark contrast to Asciidoc.
edit: A small aside, I also learned that a few publishers that focus on tech writing specifically use Asciidoc for their "publishing" workflows. So in that realm Asciidoc is practically useful to know.
For example, if GitHub fully supported AsciiDoc, you'd see a lot more people considering it. But it's just not worth the headache to them, apparently.
Common mark is a standard if you need one.
[1]. https://talk.commonmark.org/t/generic-directives-plugins-syn...
[2]. https://github.com/remarkjs/remark
[3]. https://github.com/Microflash/remark-callout-directives
With Asciidoctor, we produce decent-looking PDF documentation as well as HTML.
Why does Markdown bother to have * and ** markup? Why not just use "<i>", "<b>", "<em>" or "<strong>"?
1. An admonition is no more "just styling" than is Markdown emphasis or strong markup, exclamation points at the end of a sentence or bullet lists (why not just use commas and "and"?). Admonitions are semantic.
2. HTML is not the only output rendering for Markdown.
You pretty much do this anyway in asciidoc, just with extra steps.
Oh, and github strips out style tags, so it doesn't work there.
TIP: my tip
Super helpful when you're writing a book. My blog provider uses MD and I no longer have these handy popups or cool sidebars. I won't even get into tables etc.
Include is a bit problematic but having a way to have 1 chapter = 1 file is wonderful. You can then package the whole book with a file that lists the includes. Very convenient.
On the other hand, if you're documenting an end product with complex print output, hundreds of (slightly) different configurations, and need transclusion, partial transclusion, conditionals - to say nothing of wacky tables and olists- you end up with a giant pile of Markdown customization. It's easier to just use Asciidoc off the shelf, not to mention that you get DocBook interoperability, which lets you transform to all sorts of weird old formats.
But that complex use case often comes with dollars attached for big proprietary solutions. Asciidoc is a an open standard in a space that usually has vendor solutions.
One of the most powerful features of Markdown is that it's just text, and you don't need to learn some deep programmer lore in order to use it. Those extra features do come at a cost, such as being to tied to a single Ruby implementation and not having been ported to countless other languages because a Markdown parser is so much easier to write. And Crafting Interpreters was written in Markdown [1], you wouldn't think it because it's so beautifully formatted. Markdown is enough, simplicity wins.
[1] https://journal.stuffwithstuff.com/2020/04/05/crafting-craft...
Org mode does most of that, too. And a lot more. And while you cannot use it in Github issues, you can in README files on Github.
But yeah, to unlock the true power of org-mode you need emacs.
- Markdown beat Asciidoc
- Swagger beat RAML
- C++ beat D
- more
Each of these gained traction over the other, and each had things that made them less perfect than the other.
Markdown had vague or missing areas of specification that led to incompatible implementation. Swagger couldn't do everything, or did some things in multiple ways where RAML had a normalized syntax. D theoretically improved on C, and still lives on.
Markdown had more users, and more tooling.
Swagger had the Swagger UI.
C++ had Bjarne Stroustrup and tooling.
On the up-side, sometimes these stories come 'round again. Windows beat Mac... But Mac's still here and still gaining traction.
Maybe Clojure will be more popular than Go one day. Maybe we'll all chuck YAML for EDN or TOML. It could happen.
All of the projects that succeed through the worse is better principle is because they were easier to implement, and thus, easier to ship first and early. They have to be just good enough for their intended purpose, with relatively few competing alternatives at the time.
Only after those projects became more popular, do the warts show up, and then newer projects/iterations thought up as a replacement - which, of course don't succeed because the marginal improvements don't cover the costs of replacement.
They've been on a ever-so-slight decline (~ -3%) since the 2020's. On the other hand, Windows is stabilizing it's slow decline.
Total bait and switch in terms of the simplicity "sales pitch".
My expectation was that there would be some kind of script (just one, possibly all in one file) which scans the simple input syntax and outputs it into several markup formats based on some command line option.
Just wish the documentation were so absolutely awful -- extremely bare and hard to find examples. Enumerated values poorly explained, if at all.
The AsciiDoc docs got an overhaul 2 years ago. I find them to be quite good.
What are enumerated values? Do you mean ordered lists?
Is the Python3 asciidoc (any of the several that have sprung up) good enough to replace asciidoctor nowadays?
So this statement:
> First off, it's a single implementation.
Is a bit misleading. It's more like there are no several flavors, like with markdown.
That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Manual line breaks are too infrequently used to warrant such an unconspicuous markup with such a frequently used character IMHO. It's also totally arbitrary and not backed by widespread precedent. Just use <br> for heavens' sake, you can at any time just copy-paste it to reduce the chore, its semantics are among the most published text markup conventions ever, and it's in most situations unique enough to be safely searched-replaced in a document without all the headscratching that /\+(?=\n)/ vs /\+(?!\n)/ entails. Plus, <br> is impervious to reflowing paragraphs. What's not to like?
Trailing + for breaks is for one-offs exceptions, usually with semantic reasons. If you are manually flowing a paragraph for some reason (mostly, that’s an antipattern, but...), rather than indicating a single special break, where “rewrapping” is a thing that makes sense, then using the [%hardbreaks] directive on the paragraph makes sense; there's also a document-level toggle in the header if you want to do this for a whole document. (And many of the contexts where you'd want hard breaks have their own block type, with other linked formatting changes: literal, listing, source, and verse blocks.)
I was reviewing a command-line MD reader today. I think it was the nth time I've looked it over. It's called glow : https://github.com/charmbracelet/glow
I always come to the same conclusion. I don't need it. I don't need to remember to use (yet) another command line program to read MD or perform a very specific (and non-vital) function.
The reason is that MD and AD are so very easy to read. They are too effective at their jobs. They aren't like HTML tags that get in the way of the text. You barely even notice MD/AD in most(?) cases. Text plus MD/AD are incredibly easy to read without a 3rd-party program "rendering" the results.
Having said that... the only time I got really excited about MD/AD was when there was a post about Textual Markdown : https://news.ycombinator.com/item?id=34028765
It wasn't that the "rendered" text looked great (it looked beautiful, btw) but I could see 'Textual Markdown' turning into a command-line, online browser just for MD text! Think about that...
I even thought about how great it would be if the GeminiSpace folks : https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vect... : embraced MD/AsciiDOC instead of their limited markup language.
It's exciting to think of MD/AD making themselves an alternative lightweight tagging system on the web. Exciting to think about a lightweight web in general - no tracking, adware, tons of JS, etc...
Exciting to think about a bunch of browsers growing out of this (ie; you don't need billions/yr to support MD/AD browsers) - from full-blown GUIs to, well... "Textual-Markdown".
Anyway... MD/AD would be great if it grew beyond offline use. For offline use only... you really don't need rendering. Maybe it helps a bit with really long files but otherwise...
Feel free to use a trailing backslash for the same thing.
line one\
line two
Features like table is the ultimate conundrum - if you want beautiful text based tables like in reStructuredText it becomes very difficult to write and edit unless you use a specialized editor, while Asciidoc’s table syntax is very code-like and is completely unreadable as a tabular table (almost like a simplified HTML markup).
Markdown strikes a middle ground where it tries to be readable while being as easy to write by hand as possible. However in practice most people don’t bother to keep the columns aligned by hand so it still becomes quite unreadable, and you still need specialized editor to do align columns automatically if you want to retain readability.
You can consider it a good compromise or failing at both tasks (I view it as the latter).
Markdown is also wildly inconsistent - why have fenced codeblock feature with info string to set the language, when you can’t have fenced blockquote with info string to set the “cite” attribute?
I’m actually quite fond of reStructuredText but without widespread support it’s hard to justify investing into a much less portable format.
In the engineering and technical writing fields where multiple departments have to align on a method of building documentation and technical content for users, the goal posts are shifting a bit. Many teams need to provide data that an application will parse and render in some way, and HTML is a poor choice for that. At the same time, just sending markup over the wire has serious shortcomings.
I see Markdoc (https://markdoc.dev/docs/overview#how-markdoc-works) as an early entrant to the next generation of approaches to this problem: source content --> AST --> render. You _can_ write in Markdown and spit out HTML, but that technique is sort of superseded by all the additional functionality (some of which designed to make Markdown a bit more like Asciidoc).
That last one can be a pretty big deal, as it involves swallowing a fair amount of liability. No one wants to spend the extra cash on writers who know how to git, they'd rather get late middle age chair warmers who've been suckling down a TW2 salary their entire professional life. Leadership would rather leave the tech stuff outside the org.
The trick here is that most of these XML pubs vendors couldn't give ten strained s##ts for liability, and they disappear on pubs teams with depressing regularity. Usually right before some big contract deliverable. How's your low risk option looking now?
I think this is actually a great example of how dedicated Dan Allen is to the project! He has been following up on the ticket for over 6 years!
I have interacted with him briefly on the Antora Zulip Chat a couple of times and he is always very helpful, it's a pleasure.
I am not sure what the worry is with backward compat. The only difference with the resultant HTML, is extraneous "p" elements would be removed from "li" elements. Anyone who has been relying on that behavior, has been relying on non-idiomatic HTML and should be inconvenienced.
?? Markdown is the opposite, no? Ability to format text in an editor that looks sufficiently like formatted final text so you don't need to render it all the time.
That's what I like about markdown anyway.
Try writing something in your text editor of choice, and hard wrapping it at 80 columns. You then paste it into a github issue, and you'll see that the line breaks are preserved. It gets pretty annoying, even if all you have to do is join all the lines in the paragraph/section.
I'm not advocating for a total decoupling of presentation from raw code, but I do think that significant newlines are a point of particular irritation.
I've had a brief play with trying to implement AsciiDoc in Rust (and others have too, see https://github.com/Veykril/pagliascii). I got bored of trying to figure out what the semantics should be by reading the implementation and decided to wait until the upcoming specification effort at https://asciidoc-wg.eclipse.org/ bears fruit, the Zulip seems a bit more active recently
There are JVM (via Jruby) and JS (compiled by Opal) versions of Asciidoctor, to the extent that is a problem with the Ruby version.
* Opening the article with the problem of the line break being a trailing white space is… odd. I have written tons of Markdown and I can count in one hand the number of times I’ve had to do this. Most prose doesn’t have hard line breaks: it has paragraphs, which are easy to represent.
* As for list formatting, see this https://jmmv.dev/2022/07/markdown-lists.html , which fixes the problem for Markdown. It may not look pretty, but it works consistently AFAICT.
In any case, yes, the warts that Markdown has are annoying.
The main problem, as author has noticed, is the single implementation. That significantly limits its usage and support in other tools. And to my understanding it's because the owners of the format had overprotected it with trademarks and so on. So no one wants to make another implementation because it's easy to get into legal troubles.
Note that Asciidoctor (the Ruby implementation) has a reasonable solution now, but it's not portable to Asciidoc (the original python implementation).
. Foo
. Bar
. Baz
Markdown is more intuitive to understand, and the idea is that it's human readable even if not rendered.
1. Foo
2. Bar
3. Baz
I'm not a fan of using 1. for each bullet point, as that takes away from the "readable source code" paradigm. On the other hand, it avoids a change in indentation if you have ten or more items.
Don't most Markdown implementations allow you to use an empty line as a paragraph separator as well?
For the 'real' documentation, asciidoc (with include, I think not every implementation make the work) is generally the best. Because of includes especially, that the salient point makes asciidoc better than Latex (that I prefer generally for everything else).
Reading package lists...
Building dependency tree...
Reading state information...
The following additional packages will be installed:
asciidoc-base asciidoc-common asciidoc-dblatex asciidoc-doc dblatex
dblatex-doc docbook-dsssl docbook-utils docbook-xml docbook-xsl dvisvgm file
fonts-droid-fallback fonts-gfs-baskerville fonts-gfs-porson fonts-lato
fonts-lmodern fonts-noto-mono fonts-texgyre fonts-urw-base35 ghostscript
....
x11-common x11-utils x11-xserver-utils xdg-utils xfonts-encodings
xfonts-utils xml-core xmlto xsltproc xvt
0 upgraded, 271 newly installed, 0 to remove and 4 not upgraded.
Need to get 455 MB of archives.
After this operation, 1,127 MB of additional disk space will be used.
Do you want to continue? [Y/n] Abort. # apt install asciidoc
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
asciidoc-base asciidoc-common docbook-xsl xsltproc
Suggested packages:
asciidoc-doc docbook-utils source-highlight dbtoepub docbook-xsl-doc-html | docbook-xsl-doc-pdf | docbook-xsl-doc-text | docbook-xsl-doc docbook-xsl-saxon fop libsaxon-java libxalan2-java libxslthl-java xalan
Recommended packages:
asciidoc-dblatex xmlto
The following NEW packages will be installed:
asciidoc asciidoc-base asciidoc-common docbook-xsl xsltproc
The other thing is that, it was not easy to work with LaTeX in asciidoc last time I was doing it.
Smaller issues: the syntax really sucks.