AsciiDoc (the format) is currently being developed in an Eclipse Foundation working group (https://projects.eclipse.org/working-group/asciidoc). This working group includes leads from both the Asciidoctor/Ruby and Asciidoc/Python projects. (I'm lurking on the mailing lists but not really part of this effort.) It seems like the goal is to shore up the AsciiDoc standard and prevent further divergence between Python AsciiDoc tools and AsciiDoctor.
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.
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.
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.
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.
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").
I've now written a book using asciidoc and I am not a fan. It's full of oddities and minilanguages and special cases. For the main body of the work it was no quicker or easier than Markdown. For anything complex I wound up spending hours poring over the docs, stackoverflow, ancient forum posts, github issues trying to learn the magic incantations.
I would have greatly preferred LaTeX or DocBook, but the offered alternatives were Word or Google Docs.
I have high hopes for asciidoctor as in the text processor/converter, and the sooner I can have one less thing I need TeX for, the better.
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.
I've been using Python Sphinx for a number of years and mostly happy with it. The major limitation for me is it doesn't support "parts of a book." For whatever reason the maintainers have not been interested and ignored pull requests for it for years, saying it needed to be designed first. Then not responding to requests for feedback.
Not sure if moving a book to asciidoc is practical, but I've been considering it.
Inclusions are absolutely stellar, I know some people dismiss Asciidoctor because it feels neither here not there kinda lang. It amazes me how pliable the tool actually is (for Rubyist off course), there are some things there that would make org-mode aficionados and LaTeX die-harts envy.
I feels and works more like a real programming language while still having uncluttered syntax, you have variables, cases, etc. You can make your own plugins relatively easy. It's not in your way when you are writing.
Asciidoctor being written in Ruby is both a blessing and a curse. You could off course use Opal transpiled Asciidoctor.js if you fancy that. It works very nicely in some situations, just don't expect it to do absolutely freaking everything. Maintainers are doing a fantastically good job considering how few they actually are and how much it requires. Ruby is fun to write but not fun to debug.
After writing a reasonable amount of asciidoc, I fgure i might just as well use LaTeX, possibly unless it's sufficiently simple, and I'm expecting people to read it directly. I've found juxtaposing somewhat-presentational markup, like meta-variables in input, particularly problematic, apart from continually having to look up how to do things.
That said, it seems to be the best of the genre that I've used and implemented over the decades.
What’s your toolchain look like for converting latex to HTML, possibly with raw HTML in the latex source? I’d love to use latex if not for that wrinkle.
I've only played with it after finally giving up on using org files for source that others will read and ending up with markdown/pandoc/laTeX workflows, so I may be commenting from ignorance of its use cases. However, AsciiDoc felt a bit like methadone for WYSIWYG addicts---a useful tool to wean someone away from obsessive control of the minutiae of layout while writing toward unentangling the task and allowing the machine (possibly assisted by an editor/layout specialist) to deal with that stuff while the writer...well, writes.
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.
I evaluated formats for online docs for a Node.js library I was writing. Asciidoc(tor) was the only one I found that was available as JS lib (thanks to Asciidoctor.js), but more importantly, it could include marked sections from external code files within the docs.
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?
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.