📖

Technical Book

The idea behind this project is to write a technical book. Something long standing and useful instead of just about a particular technology.

Subject

I’m not sure of the subject yet.

Current possibilities:

  • Roguelike in Rust
    in FSharp, Clojure, or Rust
  • Deep Learning from Scratch
    in F# or Clojure or Rust
  • Adaptive Resonance Theory
    • Theory of neural networks that are transparent and explainable
  • Functional language implementation
    • Think Crafting Interpreters for a functional language
    • This could double as the language for my spreadsheet startup
ℹ️
This one is the current front runner for the book.

This would likely be published as a series of blog posts and then edited into a book.

Tools for Writing a Book

There are some good tools for authoring a book

Some criteria that would be useful:

  • Code execution
  • Equations
  • Cross references
    • Auto ToC and Index?
  • Cross platform to write anywhere
    • iPad, Mac and Windows ideally. Linux would be good also.
  • Publish to a blog and create a book format

Nice to have:

  • Markdown or some other lightweight markup language
  • Command line tools
  • Literate programming?

Jupyter Notebook

As a Book

Kind of the gold standard for executing code and interleaving documentation with markdown. There are some good tools for writing books using Jupyter Notebooks.

This seems to be the best tool for now using Jupyter notebooks to author books.

As a Blog

This seems like a good tool for blogging using Jupyter notebooks. This tool converts the notebook to markdown, which can then be converted to HTML using a number of static site generators, though Hugo is the intended target for this one.

This doesn’t handle deployment at all. There is a demo using netlify. I hope to use Cloudflare Pages.

fastpages from fast.ai looks really good too. It relies on Github for converting and hosting, but that wouldn’t be too big a problem. Could be really good, and the HTML can be downloaded and hosted somewhere else (like Cloudflare Pages).

Looks like fastpages uses nbdev, which can only work with Python, so this is out unfortunately. 😟

R Markdown

The other good contender is R Markdown. It is already Markdown, but knitr stitches together the code blocks and runs them. If using R Studio, you can execute the blocks independently if using R or Python.

And that seems to be the limiting factor. You really can’t interact with it unless you’re using R Studio and the languages available for interaction are limited. There’s no .NET languages or Clojure or Rust support. There are plenty of languages, but these are the ones I’m most interested in.

But it does look really nice.

Literate

Literate is a command line tool that takes Markdown and converts it into HTML or knits together a program from the source code in the Markdown.

It’s not as interactive as the other tools, but that might be a good thing for writing compiled langauges.

Verso

Verso is another literate programming tool, but it doesn’t rely on the code being embedded in the book as it’s written. Instead, comments/tags in the code mark areas that are then woven into the document at places marked.

ℹ️
Verso is my current choice. Having done some experiments, this type of tool seems the most flexible, if not the most convenient. It adapts to any language and runtime. It does intrude a bit on the source code, but allows for