Saturday, August 13, 2016

Technical Details: Tools for Writing, Typesetting, and Digital Publishing


When writing a draft, I like to use Google Docs.


  • It's easy to write from any computer
  • Making comments and suggestions is easy
  • Readers can follow along as I write
  • Version history is tracked


  • Requires putting my trust in "the cloud"
  • Formatting options are limited, though this has been improving over time
  • Lacks precision version controls (e.g., taking snapshots)


I use LaTex for typesetting. It's open source (read: free) and widely supported.

After I've gotten a draft into reasonably good shape, I'll transfer the contents to one or more LaTex files. Then I create one or more top-level LaTex files which control the formatting of the book. This allows me to use the same content with different formats. 


  • Books can be split into multiple files
  • Files can be version controlled, so I can track exactly what I changed over time
  • Page formatting can be precisely controlled
  • Compilers exist for all major platforms. I use TeXShop on Mac. 


  • LaTex syntax can be frustrating, but thankfully there are lots of helpful posts on the LaTex StackExchange page.
  • Many LaTex options can conflict with one another. For example, the memoir class provides useful defaults for typesetting a printed book, but can conflict with options in other packages. 

Digital Publishing

I use pandoc to generate Markdown (.md) and EPub (.epub) files, and Sigil to edit the .epub files for submission. 

I've found it's easiest to use pandoc to generate a Markdown file, then make any necessary text tweaks in Markdown before generating an EPub file:

pandoc AbigailBesonForEPub.tex -s -o --epub-cover-image=cover/cover1000x1600.jpg

pandoc -s -o AbigailBeson.epub --epub-cover-image=cover/cover1000x1600.jpg


  • Pandoc and Sigil are both open source. 


  • I've found Pandoc's direct LaTex to EPub conversion loses a lot of detail.
  • Pandoc's LaTex to Markdown conversion preserves most details, but can't handle some LaTex options. For example, I used the rlap option to avoid line wrapping (see below) and discovered pandoc simply deleted the affected lines.
\begin{vplace}[0.3]\begin{verse}From gray skies poured a \rlap{crushing flood} \\Through vengeance torn a \rlap{bond of blood} \\Strength alone won't stem the tide \\Yet peace was glimpsed, hold fast; abide \\\end{verse}\end{vplace}
Resulted in:
From gray skies poured a
Through vengeance torn a
Strength alone won't stem the tide
Yet peace was glimpsed, hold fast; abide
This type of error forced me to manually edit the Markdown file before proceeding to EPub editing.

Sigil is great for editing details like the table of contents. However, I've found that if I try to edit the EPub cover file in Sigil it gets lost entirely and iBooks can't find it.

Version Control

I used git for version control. I initially used a private github repository, but later switched to hosting my own on my Raspberry Pi based NAS. Similar to LaTex, git is powerful but initially daunting to learn.

Copyright 2016 Tyler Smith

T.D. Smith's books on Goodreads 

No comments:

Post a Comment