Post-Mortem: The Starling Handbook

Hey there!

I just thought this would be the right place to tell you how thankful I am for AsciiDoctor and the accompanying extensions. Just a few days ago, I finished writing and publishing a book about my Open Source library, and it was all done with AsciiDoctor. Maybe this small post-mortem will help some other authors and/or developers successfully finish their project.

My project actually consists of two books:

* The Starling Manual — a free online manual introducing developers to Starling.
* The Starling Handbook — a commercial book (e-book and paperback) that includes all the contents of the manual, but adds several additional chapters that go deeper than the manual.

Here's how I approached this two-part setup:

* There is one "index.adoc" file for each version of the book ("index-manual.adoc", "index-handbook.adoc") and for the preview PDF that can be downloaded on the sales page ("index-preview.adoc"). Each includes just the chapters relevant for the specific version.
* A Rakefile starts "asciidoctor" and provides tasks that build all the different versions.
* Here is the GitHub repository that shows parts of the setup: github.com/Starling-Manual (this only contains the free parts; the rest is in a separate repository).
* Several community members forked this repository and created translations, e.g. into Chinese (repository, result).
* I set up AsciiDoctor on my WebFaction server; whenever someone pushes a new version to one of the manual-repositories, a script uses the Rakefile to rebuild the corresponding HTML page and PDF. Thus, all the translations are always up to date, without me having to do anything.
* The PDF is built with AsciiDoctor-PDF, the EPUB version with AsciiDoctor-EPUB3.

The paperback version caused me some headaches initially. Since AsciiDoctor-PDF currently does not prevent widows and orphans, and does not support hyphenation, I initially thought it would not work good enough for print, so I looked into the LaTeX-options. However, I really liked the standard theme that AsciiDoctor-PDF provides, and it would have meant a HUGE amount of work for me (who hasn't got much experience with LaTeX) to reproduce that style. Thus, I decided to stick with AsciiDoctor-PDF and make some manual adjustments instead:

* For the print version, I manually inserted page breaks ("<<<") to prevent any widows and orphans. Sometimes, it also helped to simply shorten a paragraph or change the size of an image.
* I also changed the theme so that the text is aligned to the left instead of being justified (to prevent big gaps between words).
* These page-breaks are only inserted in the print version. (While this could easily have been done with a preprocessor, I actually created a separate branch in the Git repository that contains those changes, since I didn't want the translators of the manual be distracted by this.)

This turned out really well, without too much additional work. Here's what it looks like:



The e-book is now sold via Gumroad, and the paperback version is printed and distributed via blurb.com. By adapting the standard theme, I could easily set up the PDF with exactly the dimensions required by blurb. I decided to make the paperback version really cheap (just slightly above printing costs), but only available to customers of the e-book version (they get a link to the blurb page after purchase).

Here are a few things about the AsciiDoctor workflow that caused me trouble, and how I worked around them.

* AsciiDoctor-PDF does not support footnotes yet → I tried to avoid them as well as possible; for the remaining ones, I used horizontal rules and superscripts (^) to manually insert them.
* Cross Referencing between different chapters is not a problem in the HTML and PDF versions; in EPUB, it's a little different. For this reason, my build script automatically looked for all <<references>> and inserted the appropriate "xref". That way, my simple <<chapter-name>> references work for all output formats.
* Somehow I was too stupid to get "asciidoctor-mathematical" to work for the PDF version. I don't have too many formulas in my PDF, though, so I simply included SVG files instead.
* My image directory is outside the "src" directory with the ".adoc" files; that's not supported by EPUB. Thus, my build script copied them to the right place before invoking "asciidoctor".

Other than that, it all worked really well. AsciiDoctor simply rules! :-D

Thanks a lot especially to Dan Allen for his fantastic work on this software. I really enjoyed working with this toolchain, and I'm sure it hasn't been the last time I used it.

Cheers,
Daniel Sperl

---

P.S.:

There's just one more thing I ran into that's worth mentioning, just in case someone else is printing via blurb.com:

When the first test-prints from Blurb were delivered, the book was missing all the empty pages that follow after a chapter (making sure that each chapter starts on the right). That was really bad, because the pages were set up with different margins, depending if they were on the left or right side, and with page numbers supposed to be always on the outside. Half of the book had those numbers on the wrong side!

In all the preview tools of blurb, as well as all PDF viewers I tried, those empty pages DID show up, though. Thus, I received a refund from blurb and could upload a new version. Since their customer support did not seem to understand that this was an issue they would need to look into in their printing process, the problem would not go away with the next print, though. Thus, I had no other choice than to add white JPG images manually to each of the empty pages (urgh). An ugly workaround, but this did the trick.

Thanks for writing this up. I'm authoring a book using the Asciidoctor tool chain so it was encouraging to hear from someone who's successfully gone through the process.

I'm curious about one thing - I am working with asciidoctor-fopub instead of asciidoctor-pdf because the latter did not support building an index (at least when I last looked at it). Has that changed or does your book not need an index?

/Ashok

apnadkarni wrote

Thanks for writing this up. I'm authoring a book using the Asciidoctor tool chain so it was encouraging to hear from someone who's successfully gone through the process.

You're welcome, I'm glad my report is encouraging for other Asciidoctor users.

apnadkarni wrote

I'm curious about one thing - I am working with asciidoctor-fopub instead of asciidoctor-pdf because the latter did not support building an index (at least when I last looked at it). Has that changed or does your book not need an index?

No, you're right, this hasn't changed yet (to the best of my knowledge, at least). But since I'm always providing the e-book along with the paper version, I figured it's not a must-have: anyone can open up the PDF and easily search any terms there. Not the ideal solution, but I think it's acceptable for most readers.

Cheers!