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.