I love Asciidoc, especially with PlantUML. I have used them together on various projects to version, and host internal documentation. The code block snippet generator is super useful as well. Spring Framework documentation is a shining example of how useful it can be!
Org is also just a file format with extensions available in VS Code, vim, sublime, and Atom. I've personally used the VS Code extension, I think it works just as well as the Markdown extension.
That is a much more challenging task - even if they had planned it from the get go. One of the reasons people gravitate to Emacs is that it is much easier to build integrated systems like Org mode.
The other barrier, of course, is that it doesn't really benefit existing Org mode users/developers.
Which is a very long winded way of saying that you can use markdown for authoring actual content, and then use good old HTML for styling whatever else you want to.
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.
This is both the power and "problem" with Markdown. The "promise" (I'd say) of Asciidoc in general versus Markdown is that it aims to truly be a standard.
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.
While it's true markdown isnt a standard. What ever your tool does defines it. For source code docs converted to HTML or man pages you only have one build.
What if you have multiple tools that use different flavors of markdown? Even if you don't ever use multiple tools on the same input, you have to remember which syntax is allowed by which tool.
Key word is "few", which is why AsciiDoc is so frustrating to work with. Not on account of it's own shortcoming, but because so little activity is going on in the community to push it forward or to drive further support.
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.
> Which is a very long winded way of saying that you can use markdown for authoring actual content, and then use good old HTML for styling whatever else you want to.
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.
Because the majority of writing is text and lists. Admonitions don’t hit the sweet spot of requiring any extra-HTML markup. You can simply mark block level elements up with blocks.
You pretty much do this anyway in asciidoc, just with extra steps.
There's also a generic directive proposal[1] that enables admonitions, YouTube embeds, etc. With remark[2] plugins, markdown can be as extensible as you may need. Here's a sample plugin for admonitions[3] by yours truly.
That’s a good point. I wrote an introduction to CS course in Asciidoctor. The pure Ruby prawn stuff for rendering PNGs into PDFs, which is done bit by bit, ended up being too slow for me. I had hacks for doing fast proof-copies with low resolution images, but it ends up being much easier rendering the source into HTML and the HTML into PDF. Faster, but also requires a lot of learning about CSS page breaking which I’m sure a PDF engine would just do automatically for me. Alas, no budget for Prince CSS was available.
Asciidoctor-pdf:: this is the Ruby prawn-based thing, it's the current official path, but SVG and images can choke it. Complex customization means extensions, and that has its own overhead.
FOPUB aka docbook-xsl:: this is built in to the AsciidocFX dedicated editor, and uses the DocBook-XSL pipeline. Yeah, I know, it's XSL, but since DocBook has such a long tail there's a huge amount of customization that's possible, along with some docbook-only features like better indices, list of figures, etc. It's also very capable of chewing through thousand page books if it's in its own environment. But again, XSL.
asciidoctor-web-pdf:: this is the semi-experimental web based PDF tool, based on Paged.js, that uses the CMM Paged Media Module Level 3 (CMM PMM L3). I think this is built in to Antora now. This has the best promise, in my opinion, but it's still pretty raw, again, in my opinion. Bring your JS and your CSS hat. Chews through some huge amounts of memory . . ah wait, they fixed that.
After these you have DBLATEX, which uses DocBook->LaTeX as its typesetting, and you have the Haskell thing, and the wiki-2-PDF converter that's default in Visual Studio Code Asciidoctor extension. There's a few others that have largely stalled, like the packt build system for docx, but they're interesting. I still use the packt thing.
Yeah, it was just an example really. Going down this route of argument, do you need to move from markdown to asciidoc for admonitions, or do you really just need a good stylesheet? I would argue that the markup helper and the styling can — and usually do — end up being separate from each other.
I write all my professional docs in AsciiDoc (even made a tool to pull AsciiDoc comments out of the code and into various documents), but always disliked having to pull ruby into my toolchain.
Is the Python3 asciidoc (any of the several that have sprung up) good enough to replace asciidoctor nowadays?
1 and 2 seem to hate 3 (see issue trackers / web sites of all three) and meanwhile probably also vice versa. The discussion was quickly dragged into the legal realm by 1 in particular, which very obviously dampened number 3's initial enthusiasm.
Additionally, 2 describes itself somewhat prominently as a "legacy processor" for Python (technically correct in the current version, but legacy's meaning here is the relationship to the new Asciidoctor-specific constructs). At the same time it promises further development but nothing usable has come out of it so far.
As a Python programmer, I would simply like to see a pure Python3 toolchain. It is quite an absurd situation at this moment. For example, my blog is supporting Markdown and ReST natively (Pelican-based). For Asciidoc - my preferred language - Pelican has a plugin, supporting different Asciidoc processors, but only at the first glance. It has also to support KaTeX. This on the other hand is no problem for Pelican's native Markdown languages (simply another plugin), but the Asciidoc plugin is too high-level. It can only use Asciidoctor in this case, requiring Ruby's KaTeX gem as an extra dependency. This gem seems to be abandoned and has compatibility issues with newer Asciidoctor versions ...
2 is no option for its installation hell alone (Asciidoc3 is pure Python, simply a pip install). I don't know, if it is able to interact with KaTeX.
From what I can see, 3 would technically offer the best initial platform for further development as a package. Could be wrong, of course.
"the ability to format and fit content in your editor, loosely independent of how it would be presented to the user"
?? 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.
I was more referring to the behavior some markdown parsers have, which is that they (deliberately) make line-breaks significant.
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.
Main killer for me - admittedly because I like sharp tools, and it used to claim to be 'lightweight': 'apt install asciidoc' (and I had to delete most of it, because - for the first time ever - I got an HN message about "comment too long"):-
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.
A lot of dependecies are pulled from the (recommended) asciidoc-dblatex package, which depends, indirectly, on x11 packages. Don't install the recommended packages (whose concept is anyway in conflict with keeping a system lean) and see what happens.
How to not install recommended packages? (there wasn't a choice, and anyway not installing recommended packages often implies - rightly or wrongly - security risks).
Regarding the apt "recommended" concept, it's a generic concept of optional functionality; it's orthogonal to security. If one wants to make a generic association with security, less recommended packages -> less functionality -> smaller attack surface.
Probably because asciidoc recommends asciidoc-dblatex (used for producing LaTeX via docbook). Try 'apt install asciidoc asciidoc-dblatex-' to install just asciidoc without pulling in the other package.
Thanks, hopefully this'll turn up on a google search for someone who just wants to turn simple text markup into a PDF ('apt' didn't offer the option of not installing asciidoc-dblatex).
It lets you do the equivalent of "apt install asciidoc; apt remove asciidoc-dblatex" in one command, so avoids downloading the unwanted packages only to remove them.
"The requested action can be overridden for specific packages by appending a plus (+) to the package name to install this package or a minus (-) to remove it"
I really like asciidocs support for diagramming via the asciidoctor-diagram extension. It's supports lots of unique and useful diagramming formats, such as graphviz, ditaa, bytefield, etc.
I like Asciidoc and think it's a perfect format for tech documentation. It has all you need for cross referencing in docs, great table support, notes, etc.
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.
We adopted Asciidoc at work (migrated from Word and Markdown), and it has been a stellar tool for editing and reviewing our technical documentation, as it fits well into our code review process. We also use Mermaid and PlantUML for our diagrams, which the asciidoctor extension has handled well.
Everything in that article is why I don't like asciidoc. I think a lot of documentation should be absolute dead simple - no macros and complex behavior. It should just work. Markdown is great for that.
You get links, if you need more than that you're probably overcomplicating your documentation. Transclusion might sound nice, but now your docs have depedencies and they become harder to send, harder to host, and harder to edit (is this edit in this transcluded file going to work for every other file that includes it?). Then someone goes "I use it for templating" and now you have a CMS. It's a slippery slop that markdown sidesteps by going "no. You get links. If you need more than links, you're probably overcomplicating your documentation".
I find this view a bit simplistic. As a reader I find it much easier to follow if I don't have to piece information together from different documents. Including relevant sections in the correct place will improve the flow of the text a lot.
I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter.
I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).
That, honestly, feels like a problem with the markdown reader, not the format itself. A problem common to modern browsers, but also prevalent in many doc readers: Much like how a good code editor can show you "the thing you need to resolve" inline (e.g. looking up the definition of a function you highlighted), a good markdown reader should be able to trigger what looks like a transclusion in the document you're reading when you click a link, in addition to the normal link resolution.
Hmm, but you will probably like to link to something, right? Do you just put links in your Markdown? Do you link to markdown files an post-process when rendering to HTML (or maybe you don't render it at all)?
I wrote a couple of books in asciidoc. MD might work for a web comment but if you want to write something sophisticated like a book you need more. E.g.
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.
I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2]
This statement is case in point that most documentation is dirt simple.
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.
I tried installing it years ago (in a GNU/Linux distro, using its packages); it needed so many dependencies (like hundreds of megs), and in the end didn't work.
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.
Aside from the merits of Markdown and Asciidoc, Asciidoc has a name that doesn't help. Depending on the (natural) language, ASCII (the encoding, that is) annoys anything from a small percentage of users (e.g., English, Esperanto), to many people (e.g, Dutch, German, French), to almost everyone (anything that doesn't use Latin characters). In the context of a markup language intended for structuring normal text its name just screams obsolescence for a lot of potential users!
Absolutely, or at least I was also put off the name when I first heard of it. The name sounds like something that requires you to use (HTML) entities or some kind of Unicode code point syntax if you want to input non-ASCII. Blegh…
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.
It's not accurate to say AsciiDoc only has a single implementation, there is the original AsciiDoc written in Python, and also there is AsciiDoctor written in Ruby. Unfortunately, AsciiDoctor is merely _mostly_ compatible and deliberately opted to not support some features. (And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files; whether you should conform your documents to this environment depends on what you're doing with them.)
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.
I love working with Asciidoc. For me, it's the right balance between Markdown and Latex. I like Org-mode quite a bit too, but Asciidoc, when paired with Antora for generating static sites and asciidoctor-pdf for generating PDF files, creates much better looking documentation than I've been able to achieve using Org-mode.
I love AsciiDoc and want to use it more. The main problem is, as noted, that it's hard to get this ruby library into whatever platform you want to deploy to. Consequently it's hard to build tooling based on AsciiDoc.
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
> For example, Markdown has a syntax for inserting a break, inside a paragraph. You put two space characters at the end of a line, and the parser will inject a line break.
Don't most Markdown implementations allow you to use an empty line as a paragraph separator as well?
I used asciidoc to write a book with Manning, and what I have to say is that I'm personally not a fan. The main reason is the tooling in ruby. Maybe if asciidoc was more popular than it would have more implementations in more languages, but it's really tedious to work with it in the current situation IMO.
The other thing is that, it was not easy to work with LaTeX in asciidoc last time I was doing it.
I read the thread, and it is said that by now the implementation cannot be changed without breaking a lot. But there are multiple workarounds and fixes you can apply depending on your situtation. There also seems to be a new HTML renderer where the problem is already fixed.
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.
the issue is still open, and for good reason. whatever excuse they may have, the current HTML output for lists is not idiomatic, and their suggestion is essentially to use CSS hacks to fix the problem. sadly the AsciiDoc version with the problem is the one being used by GitHub itself. So until the issue is properly fixed, a new version pushed, and the new version accepted and put into use by GitHub, I am not interested to switch. This could all happen in a week with the proper motivation.
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.
123 comments
[ 5.4 ms ] story [ 293 ms ] threadOrg 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.
[1]. https://orgmode.org/install.html
I can't help but feel like it would be a lot more widely accepted if they divided it in multiple projects each with their own goals and requirements.
The other barrier, of course, is that it doesn't really benefit existing Org mode users/developers.
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.
Common mark is a standard if you need one.
What if you have multiple tools that use different flavors of markdown? Even if you don't ever use multiple tools on the same input, you have to remember which syntax is allowed by which tool.
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.
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.
[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.
Asciidoctor-pdf:: this is the Ruby prawn-based thing, it's the current official path, but SVG and images can choke it. Complex customization means extensions, and that has its own overhead.
FOPUB aka docbook-xsl:: this is built in to the AsciidocFX dedicated editor, and uses the DocBook-XSL pipeline. Yeah, I know, it's XSL, but since DocBook has such a long tail there's a huge amount of customization that's possible, along with some docbook-only features like better indices, list of figures, etc. It's also very capable of chewing through thousand page books if it's in its own environment. But again, XSL.
asciidoctor-web-pdf:: this is the semi-experimental web based PDF tool, based on Paged.js, that uses the CMM Paged Media Module Level 3 (CMM PMM L3). I think this is built in to Antora now. This has the best promise, in my opinion, but it's still pretty raw, again, in my opinion. Bring your JS and your CSS hat. Chews through some huge amounts of memory . . ah wait, they fixed that.
After these you have DBLATEX, which uses DocBook->LaTeX as its typesetting, and you have the Haskell thing, and the wiki-2-PDF converter that's default in Visual Studio Code Asciidoctor extension. There's a few others that have largely stalled, like the packt build system for docx, but they're interesting. I still use the packt thing.
Oh, and github strips out style tags, so it doesn't work there.
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.
1. https://asciidoctor.org/
2. https://github.com/asciidoc-py/asciidoc-py
3. https://asciidoc3.org/
1 and 2 seem to hate 3 (see issue trackers / web sites of all three) and meanwhile probably also vice versa. The discussion was quickly dragged into the legal realm by 1 in particular, which very obviously dampened number 3's initial enthusiasm. Additionally, 2 describes itself somewhat prominently as a "legacy processor" for Python (technically correct in the current version, but legacy's meaning here is the relationship to the new Asciidoctor-specific constructs). At the same time it promises further development but nothing usable has come out of it so far.
As a Python programmer, I would simply like to see a pure Python3 toolchain. It is quite an absurd situation at this moment. For example, my blog is supporting Markdown and ReST natively (Pelican-based). For Asciidoc - my preferred language - Pelican has a plugin, supporting different Asciidoc processors, but only at the first glance. It has also to support KaTeX. This on the other hand is no problem for Pelican's native Markdown languages (simply another plugin), but the Asciidoc plugin is too high-level. It can only use Asciidoctor in this case, requiring Ruby's KaTeX gem as an extra dependency. This gem seems to be abandoned and has compatibility issues with newer Asciidoctor versions ...
2 is no option for its installation hell alone (Asciidoc3 is pure Python, simply a pip install). I don't know, if it is able to interact with KaTeX.
From what I can see, 3 would technically offer the best initial platform for further development as a package. Could be wrong, of course.
?? 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.
If you want to disable the recommended packages installation by default, you can:
You may also want to disable the suggested packages:"The requested action can be overridden for specific packages by appending a plus (+) to the package name to install this package or a minus (-) to remove it"
https://manpages.debian.org/bullseye/apt/apt.8.en.html
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.
I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter.
I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).
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.
[1] https://github.com/alessandrocucci/book-template
[2] https://turnoverbook.com/
From my experience you need to use custom syntax for those which means tooling doesn't work well. (grammar, spelling, style etc.).
O'Reilly and Manning standardized on asciidoc.
I remember using extensions/filters for citations, etc.
Ultimately it is just some custom tooling around pandoc; so whatever you can do in pandoc, you can get done in the book.
[1] - https://github.com/chdemko/pandoc-latex-admonition
[2] - https://pandoc.org/
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.
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.
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.
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. ;_;
ref: https://github.com/github/markup/issues/1095
Note that Asciidoctor (the Ruby implementation) has a reasonable solution now, but it's not portable to Asciidoc (the original python implementation).
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?
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.
Don't most Markdown implementations allow you to use an empty line as a paragraph separator as well?
[1] https://antora.org/
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.
https://github.com/asciidoctor/asciidoctor/issues/1087
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.