Asciidoctor for collaborative book writing

(Last Updated On: January 4, 2018)
Imagine having a tool that can automatically detect if you are using JPA and Hibernate properly. Hypersistence Optimizer is that tool!

I’ve been searching for the most suitable tools I’d use for my book writing process and I’ve settled for Asciidoctor.

In the first place, I decided to use a markup text language that’s implicitly supported by GitHub, and after reviewing Markdown and Asciidoc, I opted for the latter for it offers a richer syntax.

The only problem with Asciidoc is Windows. The a2x command uses xmllint, and therefore you must use Cygwin or a virtual machine with a Linux image. This is not what I aim for, and therefore I continued evaluating git-scribe.

This is a tool meant for writing ebooks, and it’s pretty cool unless you use it on Windows. After manually installing all its dependencies (ruby, asciidoc, xsltproc, source-highlight, apache fop), I somehow managed to generate a HTML book example, but the PDF generation didn’t work. The Apache FOP classes were not found, and since I’m no Ruby expert, I simply gave up and decided to try Asciidoctor.

Running on Ruby, Asciidoctor simply works like a charm. I managed to install a Ruby file watcher that automatically generates the HTML version of my markups. PDF works and the syntax doesn’t scare me a bit. There are small differences between the original AsciiDoc and the new Asciidoctor, but that’s neglectable.

Download free ebook sample

Newsletter logo
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence,
  • a 10% discount coupon for my book.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Want to run your data access layer at warp speed?