The idea behind this project is to write a technical book. Something long standing and useful instead of just about a particular technology.
I’m not sure of the subject yet.
- in FSharp, Clojure, or RustRoguelike in Rust
- 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
- 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?
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.
Books with Jupyter
The Jupyter Book Gallery : A gallery of community books that have been created with Jupyter Book. The QuantEcon Python Lectures : A full mathematical textbook built with a custom Jupyter Book theme.
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. 😟
We are very pleased to announce the immediate availability of fastpages. fastpages is a platform which allows you to create and host a blog for free, with no ads and many useful features, such as: Create posts containing code, outputs of code (which can be interactive), formatted text, etc directly from Jupyter Notebooks; for instance see this great example post from Scott Hawley.
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 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 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.