The previous commit broke the HTMLification of the first table in this page; I
have a guess as to why. I think it's the MarkDown separated link dealie.
Isolated commit to test the hypothesis.
The one big page was taking a long time to render in the browser on GitBook,
for whatever reason. This structure should also be clearer overall, I think.
At the moment, if we want our examples to work live, we have to host them on a
webserver that doesn't insist on upgrading to HTTPS. Which means, annoyingly,
that they have to live in another repo. I've set that all up, and now the
listing of example code mainly just points to that separate domain.
It seems that GitBook v2 doens’t properly handle links to anchors within pages
(e.g. `foo.md#section`) in this file anymore. It transforms the anchor
fragments into sub-paths (`foo/section`), which then appear as either TOC
nodes or empty in the rendered doc. So basically it's all confusing and broken
if you use anchors. Too bad, since this TOC was spelled out in detail!
One potential solution would be to break the current docs into lots of smaller
files, since those kinds of links seem to work OK. Or, maybe there's a way to
get it to deal with anchors correctly.
Restructure the docs, using `.gitbook.yaml` to rename `README.md` to
`index.md`. This means that then `README.md` can be meta-documentation,
describing how this repository works and how to contribute to it. I think
that's a very preferable structure.
Peter Williams
Phil Rosenfield