The Making of “Demeter and the Commons of Being”
As a self publisher I need a reliable process chain to produce perfectly typeset print pdfs and ebooks from one source. I hate to maintain different formats with different programs and source files. In this blog post I describe my personal single source multi channel publishing setup.
The source
The original text source file of “Demeter and the Commons of Being” is a plain text file. I use markdown as a simplified markup language to mark headlines, footnotes and other text decorations. The advantage is that I can use a simple text editor to write my books. A markdown text file looks like this:
# Baking Bread
When people begin to bake their own bread, they are soon astonished at the simplicity of the task.
Markdown does not clutter your text with ugly markup tags.
The version system
When you use plain text to write your book you can use a powerful version control system such as Git or Mercurial. My personal preference is Mercurial, but from time to time I also use Git. I wrote about the advantages of a version control system before. For now the most important advantage is that I can push all changes to a repository on the web. This gives me a backup of my project and I can keep files in sync on my desktop and my notebook. I use Bitbucket and my own server.
Authors, editors, correctors and other co-workers could drastically reduce their overhead cost to maintain their projects if they could agree to use plain text files and a version control system to synchronize their computers – but, alas, they love to waste their time sending around huge word files via email.
The project folder
The first thing I do, when I start a new book project is creating a new folder, set up version control and create some boilerplate. A typical project folder contains the following files:
- text.md – the markdown text file with the content of the book
- Makefile – GNU Make is a program to automate the creation of the different output formats. More on this later
- includes.tex – a file with LaTeX code to customize the pdf creation.
- images if need as PNG or PDF
- a folder called “build” to store the generated output formats
Pandoc
I use Pandoc to create a pdf file via LaTeX and a file in EPUB-format. The latter is an ebook format which later gets converted to Amazons proprietary ebook format. The pdf file is upload to Createspace as book content.
The Makefile
Pandoc is a versatile document converter, with a lot of input formats and a lot more output formats. It is called on the command line. I don’t like to type in the command with a long line of options. So I use GNU Make. With GNU Make all I have type to generate my output files is:
make
My Makefile is not optimized. I want to improve it. But it works and it looks like this:
PANDOC = ~/.cabal/bin/pandoc
DOCS = demeter-en.md
OUTDIR = build
REV = $(shell hg id -i)
TARGETNAME = demeter-en
all: pdf epub
pdf:
$(PANDOC) --variable classoption=smallheadings --latex-engine=xelatex \
--variable fontsize=10pt --variable documentclass=scrbook --variable \
lang=english --variable mainfont='Gentium Book Basic' --variable \
sansfont='Gentium Basic' -H includes.tex \
-o $(OUTDIR)/$(TARGETNAME)-$(REV).pdf $(DOCS)
epub:
$(PANDOC) -o $(OUTDIR)/$(TARGETNAME)-$(REV).epub $(DOCS)
.PHONY: clean
clean:
rm $(OUTDIR)/*.epub $(OUTDIR)/*.pdf
rebuild: clean all
I don’t want to comment the file in detail. If you are familiar with GNU Make you understand it anyway.
It starts defining some variables, spelled in capitals. The first variable points to the pandoc executable. My pandoc executable lives in .cabal/bin. Some variables are self explanatory. An interesting variable is REV which is included in the file names. REV is defined by the shell output of the command “hg id -i” which gives back the hash of the last commit. The hash is a unique identifier. It becomes a part of the file names so I always know from which version the output files were created.
After the variable follows the command short cuts. Eg. “pdf” is the short cut for the command to produce a pdf via LaTeX. As you can see the command is very long. This is because you can pass a lot of option to LaTeX. The command to produce a epub file is much shorter. When I type “make” I trigger the short cuts for pdf and epub creation and two commands are executed:
juh@sokrates:~/Projekte/Literatur/demeter-en$ make
~/.cabal/bin/pandoc --variable classoption=smallheadings --latex-engine=xelatex --variable fontsize=12pt --variable documentclass=scrbook --variable lang=english --variable mainfont='Gentium Book Basic' --variable sansfont='Gentium Basic' -H includes.tex -o build/demeter-en-d58489b7b78a+.pdf demeter-en.md
~/.cabal/bin/pandoc -o build/demeter-en-d58489b7b78a+.epub demeter-en.md
The first long command produces the pdf file, the second the epub. The files are written in the folder “build”. They are called “demeter-en-d58489b7b78a+.pdf” and “demeter-en-d58489b7b78a+.epub”. The “d58489b7b78a+"-part is the commit hash from the Mercurial version control system and serves as unique identifier of the version. Due to this hash I can always identify the version I uploaded to KDP or Createspace.