About

A toolchain using free/open source tools to generate both PDF and ebooks (.mobi and soon .epub) from a single set of LaTeX sources.

We used this toolchain to create the hardcopy and Kindle editions of our textbook Engineering Long-Lasting Software, along with additional design elements and macros to give our book its unique appearance.

Warning

This brief guide assumes you are very comfortable with LaTeX and the Unix development environment (using Makefiles to manage complex builds, etc.) and will teach you nothing about those things. If you haven't used LaTeX before, writing in LaTeX is more like programming than like authoring. If that scares you, this bundle's not for you. If you're not comfortable running Makefile-based builds, good luck.

There is no support. Seriously. None. Pull requests are welcome since many improvements are needed, but sadly I just don't have the time to teach people to use this. It has lots of moving parts and things that can break. When better ebook authoring tools come around I'll be happy to switch!

Basic Idea

The two major ebook file formats today are Mobipocket (.prc) and ePub (.epub). Amazon bought Mobipocket, added their own DRM to Mobipocket format, and rebranded it as "Kindle format" (.azw files); ePub is an open standard that allows for but doesn't require DRM. Amazon has since extended its format to add more support for HTML positioning, wrapping, etc; this is the new KF8 (Kindle Format 8), which is essentially a proprietary extension to Mobipocket that takes advantage of the renderers on the Kindle Fire and Kindle reading apps. Currently, this toolchain doesn't have support for the new KF8 features.

Both formats are based on HTML markup for text and embedded assets (images, etc). tex4ht was designed to output HTML from LaTeX documents. However, because of differences between "plain old" HTML 5 and the individual formats, limitations/quirks of tex4ht, and limitations/quirks of the rendering software on ebook readers, substantial surgery is needed on the output of tex4ht, and some care is needed in your LaTeX authoring. The 'mobi_postprocess.rb' and 'html_postprocess.rb' scripts perform this surgery using the powerful Nokogiri XML library as a base.

The toolchain works exclusively with the LaTeX "book" document class. There are some extensions and some limitations on what you can do. In general, every logical type of document element---chapter header, figure, sidebar, code file listing, etc.---must be wrapped in its own LaTeX macro, because the output instructions for ebook generation may differ substantially from the instructions for PDF output.

If you stick to the book elements described below, you should be able to use everything as-is. If you want to customize/add behaviors, see Customizing at the end of this README.

Requirements

A Unix-like system (Mac OS X is fine, but you need to have Unix-fu) and full installs of the following:

Ruby 1.9.2 or later, including the Rubygems library manager
The Nokogiri gem (see setup instructions below)
A full install of LaTeX2e with lots o'packages. The MacTeX installer is a great choice for Mac OS X users.
pdftex - included with MacTeX
A full install of Ghostscript and ImageMagick, for converting images for ebook output
A full install of tex4ht (may be included with MacTeX, I forget)
The kindlegen script for building the .mobi file

Setup

With Ruby 1.9.2+ installed, cd to the script/ subdirectory and run 'bundle install' to make sure the Nokogiri gem is available.
In Makefile, change KINDLEGEN to the path to your kindlegen script.
In Makefile, change the paths to various other binaries as needed.
In each of the following files, search for ::EDITME:: and edit the self-explanatory metadata:

common.tex
book_mobi.ncx.erb
book_mobi.opf

Add a cover file for the Kindle version called cover.jpeg in the top level directory. Ideally, it should be 600 pixels wide by 800 pixels wide at 72 dpi. A sample is included.

IMPORTANT: The .mobi ebook file WILL NOT BUILD unless you at least have dummy values/files for all of the above.

Adding LaTeX files and assets

If you add your book content according to the following structure, you won't need any Makefile changes. If you follow your own structure, you'll need to make substantial changes to the Makefile and to common.tex. Unless you want to burn a lot of time on this, do it my way.

Add your book chapters, each in its own subdirectory, organized as follows for a chapter called mychap:

ch_mychap/ ch_mychap/mychap.tex - toplevel file for that chapter ch_mychap/figs/ - figures (.pdf files ONLY--see below) ch_mychap/tables/ - tables (usually just .tex files) ch_mychap/code/ - tables (usually just .tex files)