AsciiDoc Language Submitted to Eclipse Foundation
projects.eclipse.org
projects.eclipse.org
I know everybody knows markdown and markdown is simple, but I have seen so many people who ended up with HTML hacks for more "advanced" features like image size/position, complex tables, and even comments.
I higly recommend trying AsciiDoc to people who needs more features than Markdown.
Also, it is much more PDF-friendly than Markdown so that you don't need weird renderer workarounds to print.
I do have to mention that sometimes advance features have tripped me and I have to spent some time figuring out why. I am sure the cli tools could use help and get better
I've even fantasized about creating a new AsciiDoc mimetype, called AsciiWeb. It would be a subset of AsciiDoc that is relevant for browsing and would sit somewhere in the middle of Gopher or text browsing on one hand and the "normal" HTML/CSS/Javascript on the other. Very easy to create, suitable for minimal document browsing and structured enough that graphical clients can make it pretty and accessible. Oh wel.. one day I'll get to it.
Changing who controls the content is a feature the web doesn't offer, except to technical people who can F12 to edit.
From the different code block implementations, to crappy tables, to trying to indent lists, and so forth.
But it's also the dumbest, lowest common denominator style of text. It's missing almost anything useful.
That it's popular is an insult to anything of quality.
That's what we have though. I don't feel cosy about a text language under stewardship either.
It wasn’t so long ago that markdown was praised for its simplicity and it’s not for nothing that everyone uses it nowadays.
Markdown is good if you want simplicity that lets you do headings, emphasis and bold, and gets out of your way. I write fiction in Markdown.
AsciiDoc is good if you want structured documents. I would use it to write a technical manual.
Maybe a problem with AsciiDoc is that its name is scary. By the name "ascii" it seems to imply that there is a specific markup for typing non-ascii stuff, instead of simply typing the regular unicode characters (in whatever encoding).
Asciidoc is much more complex and so we only have 2 implementations around (a2x, asciidoctor).
Git, in the category of DVCS, is another example.
(although I'd argue that git's success stems from not pinning down the workflow early on, like competing DVCS did).
For this reason, I'm using a blogging system (Pelican) that supports all of them (including Pythons Markdown extensions). I'm completely free to apply the best suiting variant to the topics requirements.
Exactly. For me the name "ASCII" feels like it is for older UNIX-era system experts.
The name might use to be fancy considering its initial version came out in 2002 (before markdown), but it became an unfortunate name.
This is also the reason why community uptake for asciidoc has been hard. Fundamentally we do not have any pastebin or hackmd for asciidoc.. because it is hard to build for it. Pastebin and hackmd have consistently refused to include asciidoc.
Momentum exists in the JAMSTACK space. Yet Gatsby and Nextjs play with markdown variants (MDX?) for markup. There are no asciidoc examples even in their repos .
Asciidoc is undoubtedly superior to markdown..and more importantly, is a well defined standard. But unless the core team engages with the ecosystem more, this is DOA.
Antora is quite nice and writing documentation in AsciiDoc was very enjoyable, but it was very clear how the JS implementation of AsciiDoctor was not on par with the Ruby one. We had multiple cases where the JS version would handle documents differently, or support a different feature set than the asciidoctor-cli. Moreover, the build times for the portal were extremely long (like 20-30 minutes for ~100 pages)
To write documents we all used VS Code + the Firefox/Chrome ASciDoctor preview plugin, and that worked much better than AsciiDocFx.
Going back I would probably suggest to look into other platforms, as the benefits of AsciiDoc are smaller than the amount of tooling frustrations.
I stand corrected:
https://asciidoc.org/CHANGELOG.html (Version 9.0.0 (2020-06-02))
Which needs javascript, tooling, support,etc. Asciidoc as a community has not gone down that path.
The level of documentation available and the amount of work that’s gone into the software is an enormous effort. Any missing-features or quirks I’ve googled have usually led to an existing GitHub issue that Dan is working on himself, with a carefully considered fix in the pipeline or an explanation as to how to implement the feature using the AsciiDoctor API.
AsciiDoc-the-standard is lucky to have a developer of his temperament and caliber, for his own work and for the way he encourages contributions from others.
Thank you Dan and the AsciiDoctor team!
I'm also still trying to wrap my head around the presentation side. You can use something like style sheets, but it doesn't look like the same style sheets are compatible with both HTML and PDF output (if memory serves). And if you want to output to docx format, you can do it, but again the output looks different.
Uses reveal.js under the hood.
There's also antora, which is a toolchain for technical documentation.
UPDATE: It came out I was a bit unfair as I've submitted the issue to AsciiDoctor. [0]
"In July 2016 the Linux kernel project decided to transition from DocBook based documentation to reStructuredText and the Sphinx toolchain.[8]"
https://en.wikipedia.org/wiki/Comparison_of_document-markup_...
So many markup languages...
The origins of AsciiDoc is informative. AsciiDoc is a lightweight successor to the XML DocBook format used originally to write O'Reilly computer books/manuals. Both DocBook and ePub XML add semantic elements required to describe book structure.
The Lightweight Markup Languages arose to avoid the tagsoup that is not author/writer friendly. There is a place for readable/writable content that is free of GUI editor requirements. I was once told that there is a right tool for every job.
Eclipse Foundation is much larger organization than just the IDE.