Asciidoctor
asciidoctor.org
asciidoctor.org
IMO AsciiDoc's advantage over Markdown, RST, LaTeX and others is its adoption of DocBook XML as an industrial-strength backing format. The combination of a pragmatic markup language and a proven, stable, and relatively media-independent translation target is unique and extremely useful.
I'm an enthusiastic believer in Asciidoc-the-language, but the tooling situation is confusing in parts, fragmented in others, and not really living up to its premises. This is exactly why I'm watching the asciidoc-wg project with great interest.
My personal wish is for a modern and first-class replacement for the various AsciiDoc-to-PDF flows. I'd bet on CSS Paged Media, although it's been a long haul. The current options (FO/XSLT, dblatex, and asciidoctor-pdf) all have pretty severe limitations.
If any of the AsciiDoc/AsciiDoctor devs are reading this, thank you 1,000,000 times for your efforts. It's an extremely complex project and I am grateful there's a community of talented people working on it.
Hear hear. (a.k.a. "+1", a.k.a "this")
AsciiDoc was implemented in Python. AIUI, the project got neglected or abandoned, so someone re-implemented it in Ruby to create AsciiDoctor -- same markup, different rendering engine.
Some like it, some don't. I don't mind working with it, but I haven't used it in anger. It seems pretty good. It's richer and more expressive than Markdown, which is feeble and that's resulted in multiple subtly-different, incompatible implementations.
It compares with RST -- ReStructured Text, another lightweight, human-readable plain-text markup format that's used in several places.
The advantage of ADoc is that its model maps onto that of DocBook, so it's possible to render ADoc into DocBook and then use it with established DocBook toolchains.
I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy and it took me a long time -- at least months -- to learn to read it or write it fairly easily and fluidly.
ADoc you can learn in an afternoon and the source remains perfectly naked-eye readable.
The arguable weakness is that because DocBook is a tightly-specified format, you can formally validate a DocBook document. You know it will work and render to something, even if what comes out isn't quite what you wanted.
Whereas you can't verify an ADoc document. It's possible to write something that looks fine but isn't and which might produce wildly different output from what you intended. You just can't formally tell (i.e. in software) if it's going to work or not: anything will work and produce _something_.
An advantage for humans, but a big snag if you're trying to automate making PDFs or e-books or something from it. In most cases, if you're using some form of continuous integration or something, it's preferable that it will stop with an error and tell you than for it to churn out something totally bogus.
My feeling is that part of the reason adoc is missing or a real PITA to configure for thrid-party software (e.g.: pandoc or hugo) is largely due to this.
Furthermore, I don't love the way math typesetting looks when you export to PDF (although, I guess I should just use XeTeX/LaTeX at that point).
I nearly wrote my master's thesis in adoc, and but for the build system, it was a lot of fun.
I feel sure that there must be some happy medium somewhere between the skeletal marked-up text formats of RST, ADoc and Markdown and the excessive complexity of (say) DocBook, but I don't know what it is, and if it exists, it might not be FOSS.
I used to do a lot of writing and editing for Wikipedia (before someone unjustly accused me of vandalism, and a couple of my bigger pieces were deleted -- after that, sod them, I just do minor copy-edits) and I was happier with MediaWiki markup, but I guess it's not very intuitive.
The professional FOSS documentation tools I've worked with are at one extreme -- the "Docs as Code" philosophy that holds that embracing programmers' tools such as Git and various programmers' editors mean getting a lot of power for little investment.
The other extreme are powerful proprietary tools, often on Windows, such as MadCap Flare, which I haven't worked with.
I reckon there is space in the middle for something like Wikipedia with versioning and branches, but nobody's inclined to invest in the R&D. There are tools, they work, so why should they?
The markup is actually significantly incompatible in my experience.
> I mostly work in DocBook, but I don't like it much. I personally find raw XML horribly wordy
Originally DocBook was a general SGML application, which meant you could use the short forms designed for manual input (and which provide better legibility). But, XML.
I would have greatly preferred LaTeX or DocBook, but the offered alternatives were Word or Google Docs.
AsciiDoc the language though, like RST, has lost the popularity contest to Markdown I'd say - everyone around me knows what .md is, but ask about AsciiDoc and you're most likely to get "Ascii what?".
That doesn't make it objectively worse, but I think allowing Markdown syntax as input (with metadata/annotations where needed) would give the project a boost.
Not sure if moving a book to asciidoc is practical, but I've been considering it.
This is the book: https://www.amazon.com/Deep-Learning-Coders-fastai-PyTorch/d...
This is the nb->asciidoc convertor: https://github.com/fastai/fastdoc
These are the source notebooks: https://github.com/fastai/fastbook/
https://github.com/asciidoctor/asciidoctor.js
Also take a look at Antora if you love JS static site frameworks, it's for multi repo Git and is based on Asciidoctor.js
That said, it seems to be the best of the genre that I've used and implemented over the decades.
Edit: Fix the link.
That said, there's probably a huge niche for that, and if it improves adoption of markdown-like text formats, I'm in. I'm tired of having to explain to colleagues that no, that is my original, and yeah, the syntax is really obvious and no, no you don't have to learn LaTeX, here's my style files, no, honest you just have to run a script, hell, just throw your files in the share on my server, it'll email you the results, but, oh, for the, yeah, yeah, I'll get you a bloody Word version.
However, the primary language of development of asciidoctor is ruby. The nodejs port is autogenerated from Ruby and is killing adoption.
In a world where 99% of markdown adoption is through the frontend, this is a harsh reality.
None of the pastebin, hackmd guys want to adopt an autogenerated lib.
This meant I could write code examples within unit tests, and include sections of those tests in the docs, keeping the docs in sync with the actual code and making sure the examples are still valid.
Does anyone know another doc format that supports this?
so that you don't get a shopping list like this if you type the following in a HN comment with a newline between each:
eggs milk bacon toast
well, it exists, it's BBCode