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:
- A roguelike game in FSharp, Clojure, or Rust
- Rust is the current winner in this race.
- 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 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 languages.
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.