Create multi-format eBooks from the command line - using Docker.
Run a Docker image to transform your AsciiDoc documentation to:
- Multipart HTML
- EPUB
It also makes sure that your images fit, and reprocesses them according to your destination media (for example, images for PDF are to be 150dpi, JPEGs have a defined compression ratio, etc.)
If you have Docker installed, just clone the repo, then go to "sample_book" and run "make". The sample document will be compiled to all formats - PDF, HTML and EPUB.
The Docker image expects sources to be mounted as /in and output to be mounted as /out. Though the contents of /in are read-only, it is perfectly acceptable to map /in and /out to the same folder.
You will run the Docker image as:
docker run -it --rm \
-v $(readlink -m .):/in \
-v $(readlink -m ./out):/out \
lenz/dockbooker \
/make/all
The first line runs the image and removes it when terminated. The second and third line mount volumes on /in and /out (note that we have to use readlink to make local paths absolute). The last line runs the correct command "/make/all".
A book is created out of a folder containing an Asciidoc file, its images and a manifest file dockbooker.json.
The manifest:
- Defines what to compile and how to name the resulting file
- Defines how you want your images processed
The idea is that you keep images in the simplest possibe format - be it text (for dotfiles) or high-resoution, full-color graphics.
When rendering, dockbooker takes care of rendering the images with a size and a resolution that looks good, but is usually compressed - for example, PNGs are reduced to 256 colors and packed. So for each image you can simply add to your repo the image as-is, without processing it, and dockbooker will process it.
The idea is that images can be either MAXI (full page), MIDI (about 2/3) and MINI (about 1/3 of the page).
It is possible to customize PDFs by adding Docbook customization files. The one supplied lets you add a picture on the cover page and a small logo on the footer of each page.
In theory, you can customize the appearance of Docbook books quite a lot. In practice, it's so absurdly complex that any contribution on how to do this in practice is welcome.
The supplied XSLT file includes:
- An image on the cover page, scaled to be 8.0 cm tall
- An image in the footer, scaled to be 1.0 cm tall
Feel free to improve it.
See also:
- Tips on using fonts: http://www.simon-cozens.org/content/docbook-fop-fonts-and-multilingua
- Preprocessing fonts: http://www.incenp.org/notes/2012/fop-ttf-fonts.html
- A (long) list of FOP configuration parameters: http://docbook.sourceforge.net/release/xsl/1.77.0/doc/fo/
- Fonts embedded in FOP: https://xmlgraphics.apache.org/fop/2.0/fonts.html