This book used a set of tools that are all free and open source. The authoring was plain text using the free and open source text editor, Atom editor [1] in a plain text format called AsciiDoc [2], a text-based markup language similar to markdown but able to handle more complex documents. However, any text editor will do. For windows notepad++ is a great free tool too.

Version control was performed with the free and open source tool git [3].

I prefer a modular content architecture rather than a single monolithic large document. I created the content in modular pieces (files) like legos. The main AsciiDoc file acts as a module map to the component files using the AsciiDoctor include statement.

Unfortunately for you, I am not a trained graphic artist and as an independent publisher, I have zero budget for hiring the artwork out. So you get what I make up or what I can find on sites with free usage rights and no licensing fees.

The media files get inserted by reference like with HTML and XML rather than embedded, making it easy to update them as needed with Gimp [4].

I used the AsciiDoc source content to make the HTML5 versions, PDF versions for print, and ePub [5] versions for eBooks. For the HTML versions, I used an open source tool called Asciidoctor [6] that runs on the Ruby command line.[7] A short command automatically converts the the plain text files into HTML.

For the epub version, I used Sigil [8] to create the ePub for the eBook. This was not quite automatic. However, other than importing (1) the HTML made from Asciidoctor, (2) the cover image, and (3) auto-generating the table of contents, making an eBook was easy with this tool. I recommend it. I’ve tried Pandoc [9] and Asciidoctor-epub, but both had issues that made the epub not pass the distributor’s checks. This could have been my knowledge level at the time, too.

For reviewers wanting to use Microsoft Word, I auto-converted the HTML to Word. Reviewers made change annotations in Microsoft Word that were incorporated into the AsciiDoc source files with versioning using git.

Some reviewers prefer PDF to review. For PDF, I used Asciidoctor to convert the asciidoc file to DocBook XML [10] automatically and then used asciidoctor-fopub [11] to automatically generate the entire PDF. This process takes a few seconds once you complete the non-recurring setup tasks.

At first glance this tool set may sound complicated; however, I have found working with AsciiDoc far easier than working directly with HTML5 elements, XML, Word or Pages files.

The text files with AsciiDoc markup are easy for humans even if tools like Word and Pages keep changing and don’t take this format 20 years later.


Line By Line

Here a Little, There a Little, Layer by Layer.

Back to Overview