back

by lproven·5y ago·view on hn ↗
Yup.

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.

4 comments
> same markup, different rendering engine.

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 love adoc, but I really dislike the build tools (maybe because I don't work with Ruby).

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.

Interesting. I have most of this and various toolchains installed as standard on my work boxes, so for me, for instance, to get a preview pain in Atom, I just added 2 packages and the Atom module and it worked. For Pandoc, even less -- I just installed Pandoc and bingo, I could convert to/from.

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.

https://www.docslikecode.com/

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?

It was originally started so we could integrate Asciidoc parsing into GitHub's codebase without shelling out to Python (A good friend worked on Asciidoctor and I wrote another parser for reStructuredText around the same time that we never got around to implementing in the codebase). The project sort of took off from there and has flourished into this great toolkit.
I believe the Java implementation is current and well maintained: https://asciidoctor.org/docs/asciidoctorj/
It's not a separate Java implementation, it's just a Java wrapper for the Ruby library ("AsciidoctorJ provides Java bindings for the Asciidoctor RubyGem (asciidoctor) using JRuby").