Tooling

This edition of “Mastering Dyalog APL” relies on a couple of tools to edit the book sources, build the output in different formats (such as HTML), and publish the HTML book to its URL.

The tools needed include Python 3, the Jupyter interface for notebooks, Dyalog APL, the Dyalog APL Jupyter kernel, Jupyter Book, and the Python packages listed in the file requirements.txt.

Editing the Book

The book source is a collection of Jupyter notebooks that can be found in the folder docs of the branch master of this repository. Simply start your Jupyter interface and open the notebook(s) you want to change. After editing the source notebook(s) and saving the changes, the book needs to be rebuilt.

Build Process

The build process is what transforms the source notebooks into the HTML pages available online, the book PDF, and possibly other formats.

The build process is defined by the file makefile available in the root directory and contains three main steps:

1. preprocessing: we run some custom scripts that are mostly responsible for turning the custom notebook formatting (detailed in another Wiki page) into source notebooks that Jupyter Book understands. These reformatted notebooks are stored into the folder book.
2. Jupyter Book building: the Jupyter Book tool is run, and that tool is responsible for picking up the notebooks in the folder book, the respective configurations, and then building the output in whatever format was specified (HTML, PDF, ...).
3. postprocessing: if the target format is LaTeX, some custom postprocessing plugs in the APL font into the generated .tex file.

Publishing the HTML Output

Once the HTML version is built, the tool ghp-import can be used to push the new HTML build into the branch gh-pages of this repository. This repository serves the HTML version of the book through GitHub Pages with a custom domain configuration set through the CNAME file.