Sphinx: A productivity tool for self publisher

Sphinx was built to generate the documentation of the Python programming language. Sphinx uses one input source to generate multiple output formats. The most important formats are HTML for web publishing, PDF typeset with LaTeX for printed books and ePub as ebook format.

Most self publisher want to publish their work as printed books and as ebook. So they need a tool to produce both formats in one go if they don’t want to maintain two different sources.

What are the main requirements when you publish a book in print and as ebook? A printed book has to be typeset properly to meet the quality requirements readers are used to. Many authors try to produce a book with text processors like Word or LibreOffice. Neither of them is a typesetting program, so the quality of a book made with Word or LibreOffice is poor. Even a very sophisticated programs like Scrivener, made to support the creative process of writing and very popular in the writers community, is not a typesetting program.

Typesetting is an art in itself so self publisher either use the limited features of their word processors to produce their printed books or their use special typesetting programs as last production step in their publishing process.

Scientists and many authors of computer books use the LaTeX typesetting program to produce well typeset books. Most fiction authors are not familiar with this tool and I guess they’ll never be, because LaTeX uses a rather sophisticated markup language as input format. But Sphinx gives you a hand.

Sphinx makes it easier to use LaTeX as typesetting module by using a simplified markup language as input format. The mark up language is called Restructured Text and I show an example in an other article. With Sphinx you can use nearly every advanced publishing feature of LaTeX such as references, footnotes, index, figures and tables with captions and the good typesetting quality. Most fiction writers will only need headlines which are marked in Restructured Text by underlining the headline text. All your files will be in plain text. No other text format is required. Whoever tried to open a 20 years old wordstar file knows what that means. You will be able to use all your files in 20 years or more without any problems, because you can open them with any texteditor.

When you have written your book with Sphinx one simple command on the command line (WTF is a command line?) suffice to produce a well typeset PDF and a perfect ebook.

$ make latexpdf epub

This command produces a PDF file and an ePub-file from the same source. You can take the resulting ePub file to upload it to your ebook publisher, and the generated PDF file to upload it to your book publisher.

The catch

Here comes the catch. The stable version of Sphinx can produce an epub file, but there are some issues that are annoying in the resulting ebook, for example superfluous navigation links at the end of each chapter if you use one file for each chapter. You have to use the fork by Roland Meister. And there is another catch. You need to know how to install a Python package on your computer. There is no easy installer. But many users should be able to follow the installation instructions.

So here is what I did to install Rolands fork on my Mac OS X notebook.

Open a Terminal and make a virtual environment for Sphinx. The advantage of a virtual environment is that it won’t mess up your system wide Python installation.

virutalenv Publishing

This command give you this result:

New python executable in Publishing/bin/python
Installing setuptools............done.
Installing pip...............done.

You have created a new directory called ‘Publishing’. Go into this directory:

$ cd Publishing

There are three folders in the directory, which you can see if you type the unix command ’ls’:

jan-ulrich-haseckes-macbook-2:Publishing juh$ ls
bin    include    lib

Activate the virtual environment:

$ source ./bin/activate

After this activation you use the PYthon executable in the bin folder of your virtual environment.

Now install the Sphinx fork of Roland Meister

wget --no-check-certificate https://bitbucket.org/rolmei/sphinx-epub/get/b0bbe19a853f.zip

Unzip the archive:

unzip b0bbe19a853f.zip

Change into the new folder:

cd rolmei-sphinx-epub-b0bbe19a853f/

Install Sphinx by using these two commands:

python setup.py build
sudo python setup.py install

The last command will download some required packages and install them.

Change to the root folder of your virtual environment:

$ cd ..

And have look at the new programs in ‘bin’:

(Publishing)jan-ulrich-haseckes-macbook-2:Publishing juh$ ls ./bin/
activate        python            rst2xetex.py
activate.csh        python2.7        rst2xml.py
activate.fish        rst2html.py        rstpep2html.py
activate_this.py    rst2latex.py        sphinx-apidoc
easy_install        rst2man.py        sphinx-autogen
easy_install-2.7    rst2odt.py        sphinx-build
pip            rst2odt_prepstyles.py    sphinx-quickstart
pip-2.7            rst2pseudoxml.py
pygmentize        rst2s5.py

With ‘sphinx-quickstart’ you create a new Sphinx project. So lets do it:

sphinx-quickstart MyNovel

With this commad you create a new home folder for your next novel. It is $ called MyNovel. The executable ‘sphinx-quickstart’ is an interactive script which will ask you many questions. You can safely use the default settings by using the enter key. But remember to type ‘y’ when the script asks you, if you want to use the ePub builder. Default is ’no’ which is not what you want.

When the script is finished you can change into the new folder ‘MyNovel’ and start writing your novel. Read the documentation of Sphinx to procede.

When you are using plain text files to write your novel, you can use a versioning system to keep track of changes. I described the advantages of a versioning system in an other article.

Using Sphinx gives you another advantage. Did you ever searched through the menus of a GUI-program to find an option which you wanted to change? Sphinx stores all settings in a configuration file. Just load the file in your text editor and browse to the option you want to change.

Another catch

Though Sphinx uses LaTeX to produce a high quality PDF, you will have to customize this output channel. The default PDF has a scientific layout which is suitable for books about software – have a look at my book about the content management system Plone – but not for fiction. So in most cases you will have to ask a LaTeX guru to customize the templates for you. Installing TeX on your system is quite easy, because there are installers around for many operating systems. TeX Live for Linux, MikTeX for Windows and MacTeX for Mac OS X.

Maybe for many readers there are too many catches to use Sphinx. But if you are open to new habits, you should try it out.