Burro

Documentation

As mentioned in the last post, I've been away on vacation for most of the last two weeks. I took advantage of my time on the plane to start working on an important blocker for the 0.1 release: documentation!

The docs are still very incomplete (and writing good documentation is hard!), so I won't share any snippets from the docs themselves. Instead, I'd like to talk about some experiences from writing a larger document in Burro.

Missing macros

The biggest takeaway is that macros will be very nice. This is no surprise—there's a reason they're in most every typesetting language! Currently, for each section header, I'm using the following snippet:

.hspace[-] .pt_size[+6pt] .bold[Section Header] .pt_size[-] .break

This moves the cursor to the left margin, increases the point size by 6 points, outputs the header in bold, resets the point size to the previous value, and inserts a newline and carriage return. It would obviously be nice to be able to just do .section[Section Header] and get the same result rather than copy and pasting this same line everywhere. Once we have a macro system, we'll define this .section macro along with many others. (As previously discussed, we're holding off on implementing many features that could be done with macros until the macro system is in place. Lists and sections are examples of those.)

Background colors

Changing the background color is another feature I haven't thought about much but am now missing. Specifically, it would be nice to be able to have a gray background for code snippets. I'm not sure if I'll get around to this before 0.1 or not. It will definitely be included before 1.0.

Pleasant overall

Rather than only focusing on what's missing, I'd like to affirm that overall, the experience has been quite pleasant. Burro is shaping up to be the language I set out to build. I have a clear vision of how I want it to work, and it's fun to actually start using it for a large scale project.

Font improvements

I showed the section on fontmaps to my partner while on the plane, and she found it confusing and had an excellent suggestion. Rather than relying on the user to provide their own fonts, we should bundle a small default set of fonts with Burro and use those. She's filed a tracking ticket.

This will course result in a slightly more complicated installation process. However, the end result—much easier onboarding—will be worth it. We'll still make it possible to install Burro without the default fonts if a more minimalist approach is desired.

We'll also provide tooling for editing the fontmap. This will look something like burro add-font. The overall process will be similar to mom's install-font.sh, but will try to be somewhat saner.