An ongoing text like this can use something to track its changes; this seems like a good place to start.

This webpage has been up for about five years, but I’ve started to get a little less shy about sharing links as it fills in. The intro describes what this text is, but a few other notes don’t fit in there so well.

First: This is maintained primarily as a set of R Markdown files. Historically, I’ve served those through Yihui Xie’s generally strong Bookdown package. But as I start to fit in some Python and Javascript code and generally do more complicated things involving specific parts, that’s gotten a bit more difficult. And the compile times for Bookdown have gotten excrutiating, to the point where I didn’t upload the last week’s outline from the 2021 iteration of this course largely because fixing all the compile-time errors would have been too much.

So I’m switching it over to Svelte-kit, with Tailwind CSS for the styling. This is appealing because it makes it possible to define specific routes for something like a particular chapter in a particular language.

The behind the scenes rendering keeps using some quite powerful pandoc filters I’ve used before. One of the points of this book is that programming language allow you to take part in powerful formal languages, like the grammar of graphics for visualization or regular expressions for strings. What pandoc offers is the best expressive grammar I know of for describing the constituent parts of a document. I’ve used lesser markdown parsers in the past, but never again.

Rather than build pages on this site from markdown or HTML, I render them directly from pandoc’s JSON-formatted AST. I’ve gotten so nuts, in fact, that a portion of this texts code-base has already spun off into its own package, called pandoc-svelte-components. This gives a rich way to customize svelte’s behavior anywhere inside the pandoc AST.

For the R parts, I’m still using Xie’s knitr package to do the heavy lifting, and still using R Markdown as the composition format for all languages. This means that the Python parts, even where they’re filled in, are not getting battle tested with each build. In the past I used some python book function to create things as jupyter notebook books: I think I’ll stick with the same styling here, but pandoc will make it easy to export anything as an IPython notebook.

The arquero parts are a little less fleshed out, in part because they’re so much more exciting. I’d like to be able to somehow host these notebooks on Observable, but that seems to be impossible for the time being.