Thursday, March 14, 2019

Every time I declare tab bankruptcy and close the 15 to 25 things I have open in a web browser, I suspect I’m losing state I will later regret being unable to retrieve.

That generalizes, I suppose. I have this sense that a lot of what we do in software is something like writing code before the use of version control systems became a norm.

All kinds of relationships and structures remain implicit, undescribed, and impossible to model because they live purely in ephemeral application state. The best we have in a lot of cases is fragile browser history, notification backlogs in e-mail, or logs accumulated on other people’s computers for purposes directly hostile to our interests.

Sunday, March 3, 2019

notes on notes

First of all, I wrote up some notes on my current note-taking process.

I started to do this the other day as a regular, dated p1k3 entry, but it got sort of long and I found myself wanting to do it as a standalone document that I could update over time. It seemed like a table of contents would be nice, but that’s not something that wrt supports, so I decided to see how hard it would be to add based on the hacky rendering script I wrote for userland.

That turned out to be a hassle to do well for various reasons, so I turned to Pandoc, which supports generating a table of contents out of the box.

There’s a Perl wrapper for the pandoc binary, so I first tried using that to add a simple <pandoc>…</pandoc> pseudo-tag to wrt’s markup processing the way I’ve done for Textile, Markdown, and other things in the past. It turns out that in order to get a table of contents out of Pandoc while still generating an HTML fragment (rather than a complete document), you have to write a custom template file. It also turns out that if you want to automatically put self-links next to headers, you need to write a custom filter to transform Pandoc’s abstract syntax tree.

I gave up on modifying wrt to handle this and switched to writing a small Makefile, a filter.py, and a template to generate HTML for inclusion by wrt. You can see the results here or on my gitea instance. I kind of hate the outcome and I’m not sure I’ll do anything this way again, but I definitely learned some stuff about Pandoc. I suppose this might be a useful example for someone.