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:
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:
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:
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.
