C++ Annotations is one of the best resources to learn the nuts and bolts of C++ for people who are already familiar with C or a similar programming language. This book is written and freely published by Frank B. Brokken, a lecturer at the University of Groningen, Netherlands teaching C++ courses. He keeps the book regularly updated and currently it includes up to C++17 features.

Yet this book uses a weird set of tools to build suitable output formats. Here I document the steps that I had to find the hard way on how to finally create an epub or mobi file format to use on a Kindle reader.

First of all, let’s clone the book repo:

git clone https://gitlab.com/fbb-git/cppannotations.git

The book is actively being worked on, so the latest snapshot did not build for me. I had to revert to the last tagged version:

git reset --hard 11.5.0

The author has invented an entire document typesetting system for himself just to typeset this book! It’s called yodl and it’s hard to find things with fewer Google search results than it. Fortunately, there is a Debian package for yodl maintained by the author himself. The first step is installing this package:

apt-get install yodl

The other oddity is that this package uses an arcane build system called icmake (no relation to the famous cmake), which again, is created by no other than the book author himself. It’s a good thing that he pushes his software to become part of Debian:

apt-get install icmake

The book repo does not just include documents, but it actually comes with the source code of programs necessary to build the book. The bobcat C++ library is a build dependency for these programs. If you are not good at sensing patterns like me, you have to know that this collection of C++ libraries is also written by the author and included in Debian repositories. It can be installed with:

apt-get install libbobcat-dev

To build these programs, a C++ compiler toolchain is needed:

apt-get install build-essential

After having all requirements installed, the build script at the root of the repo can be used to build the book from source files.

./build pre
./build programs
./build docs

Building the repo creates txt, ps, pdf, man page, and html versions of the book, among some other intermediary file formats. If a PDF file is enough, copy tmp/docs/latex/cplusplus.pdf to your target device and enjoy reading. But if you prefer E-Readers, unfortunately, an E-Reader friendly format is not one of the output formats. But it’s quite possible to convert the HTML format to a well-formatted epub or mobi file format.

Pandoc is my go-to document format converter, While unfortunately pandoc does not support output to mobi file format, to create the epub file we can run:

cd html
pandoc --from html --to epub2 -o cpp_annotations.epub *.html

Another method to convert the HTML book to either epub or mobi is to use the Calibre software. Install calibre package, open the program, then in the main page import the HTML directory in the repo as a book. Then right-click on the book title, select “Convert books” and follow the dialog. Calibre comes with an equivalent command line program as well:

ebook-convert html/cplusplus.html cpp_annotations.epub --title "C++ Annotations" --authors "Frank B. Brokken" --tags "C++,Programming"
ebook-convert html/cplusplus.html cpp_annotations.mobi --title "C++ Annotations" --authors "Frank B. Brokken" --tags "C++,Programming"

The resulting file using both Pandoc and Calibre programs was high quality and quite readable on the target device, including code snippets and diagrams.

C++ Annotations book is licensed freely (as in freedom) under GNU GPL. It is even available as a Debian package called c++-annotations maintained by the book author. This also means I can legally provide a copy here for people to download. So to make it easier for people like past me who do not want to venture into building books from source and just want to start reading, here are links to the epub and mobi versions of the book. These are created by the above recipe and I’ll try to update them to the latest from time to time.