Changing and updating the brhfl dot com template

It’s been a while since we had a good meta post here, which makes for a good excuse to perform a major overhaul on my template. In seriousness, this has been a long time coming. For starters, my site wouldn’t render on versions of Hugo past 0.47.1. While not a huge deal to keep old copies around, it only becomes more work as the versions roll by. None of the changes that I’ve made to support Hugo should have any visible effect on the site. But I’ve also been meaning to play around with revamping the navigation at the top. I was using this hacked-together ‘drawer’ type system to hide and reveal the categories, archive, and et cetera sections. I have preserved an archived copy of the home page with the old template intact for demonstration purposes. But I’m not doing that anymore, and let’s start there.

Ditching the drawers

When I set out to design this blog, the drawers were an aesthetic choice that I was very happy with. Archive links by month, a long list of categories… these things were immediately available, yet hidden away. A visitor didn’t need to know that it would open like a drawer, they just needed to know that clicking ‘categories’ would get them to the categories somehow. In a lot of ways this a case of murdering my darlings, and I may revisit the drawers in the future, but for now I think this is the right way to go.

I knew from the beginning that the drawers were not ideal for accessibility. I have a ‘skip’ link in place, but if a screen-reader user did end up in the navigation section (whether by choice or not), all of those lists were still there in their entirety. The paradigm of hiding individual drawers did not carry over. And while I tried to figure out how best to fix this on several occasions, I never came up with anything suitable. While I’m sure this could have been fixed, it is no longer necessary.

Removing the drawers also removes my only dependence on JavaScript and jQuery. As of now, jQuery is only loaded when a post loads a JS file. I don’t necessarily hate jQuery as much as some folks do, but it was a dependence that was there for basically one little gimmick. Similar to the accessibility angle, the site now renders beautifully in lynx:

←←←                                                 (p1 of 7)
   Skip to main content


     * about
     * categories
     * archive
     * series
     * et cetera

Changing and updating the brhfl dot com template

   bri hefele, 2019-06-25, hugo, meta

   It’s been a while since we had a good meta post here, which makes for a
   good excuse to perform a major overhaul on my template. In seriousness,
   this has been a long time coming. For starters, my site wouldn’t render

The point that really pushed me in this direction, however, was speed. Everything here is lightweight static HTML, and everything loads fast. With a 1 second open time on the drawers for aesthetic effect, the load time of a page just listing all the categories is as fast or faster. It may not be as sexy as the drawer gimmick, but moving to simple, dedicated pages is fast, functional, and allows me to play with formatting a little bit. For example, the categories drawer listed them alphabetically; I updated the categories page to have lists sorted both alphabetically and by post count. This page always existed, but you either had to know it was there or have JS disabled. It previously only had the list sorted by post count.

On the to-do list is to flesh out the et cetera page a bit more. I’ve promoted ‘series’ out of there and into the top nav itself, and have demoted my flickr page to et cetera. Not that I’m not proud of my photography or anything, but it felt a bit odd having an external link so prominently showcased. Series on this site have become a nice organizational method as well, and I’m happy to have them in the top nav.

Updating to support new Hugo versions

I occasionally regret building this thing in Hugo. The documentation is extremely hit-or-miss, the devs are quite dismissive, and they seem to live in their own little world when it comes to feature changes. The fatal error I was having was known by (at least) one of the developers to be breaking sites – it was due to a change in Go, and he raised it as an issue with that team. Yet finding any documentation on why this change affected Hugo users or how to fix it was… impossible.

The problem was that I was doing something along the lines of $value, .Page. This was never valid, it just happened to work. And that I and others somehow all came across this method of assigning variables suggests that either official documentation or tutorials once showed it. This stopped working in Go 1.11 and thus Hugo 0.48, tossing out the not-terribly-helpful fatal error: range can only initialize variables. The proper way to do this is $value := .Page, or if an index is needed, $index, $value := .Page.

Aside from that fatal error, some very useful things have been deprecated, which have been a pain to work around. For instance, this incredibly unhelpful note from the 0.55.0 changelog:

preserveTaxonomyNames configuration option is removed. Use .Page.Title.

I don’t know why URLizing (lowercasing, hyphenating, among other things) taxonomy names was ever even the default. Supposedly it was ‘by design’, but the dev links to this meaningless issue as some sort of explanation or discussion, of which it is neither. That decision was bad enough, but removing the config option to keep taxonomy names as you wrote them is patently absurd to me. So, in a ton of places like the series and category pages, I had to rewrite $taxonomy.Name to $taxonomy.Page.Title, and where I was comparing a given post’s series to the list of all series (to list all of that series’ posts in a given post’s footer), I now had to .Params.series | urlize in order to make sure it would match the absurd new format. It is entirely possible that I missed something.

I guess having everything’s name URLized does fix one of my complaints – alphabetizing was case sensitive before, so I basically had to keep all of my categories, etc., lowercase. Hack of a way to solve that, but it’s a nice side effect. I will likely go through and appropriately case my categories at some point. Also on the todo list is cleaning up a handful of warnings Hugo is throwing at me – more stuff being deprecated, huzzah.

One more accessibility note

Unrelated to template changes, but relevant for a meta post: a reader shot me an email rightfully complaining that one of my longer posts wasn’t broken up into subsections with headers. I fixed that post, and a few others as well. One nice thing about a system like Hugo is that I can just feed every raw file into wc and get a big ol’ list which I can sort to get a general idea of which of my posts are long. I know I have very small readership numbers here, but that isn’t a great excuse for letting things slip when it comes to accessibility. I’m going to try to have a better feel for the scope of posts and break them up when necessary. And of course, as mentioned, the template changes I’ve implemented should prove beneficial in an accessibility context as well.

Acrobat: The disparity of tagging methods

Prompted both by troubleshooting a comrade’s accessibility work (related to this short RPG collection which you should absolutely check out!) and a recent instance of tags in a work document turning to random bytes, I thought it might be valuable to briefly go over the three main ways to tag elements in a tagged PDF in Adobe Acrobat. Ultimately they should all do the same thing, but because it’s an Adobe product, they all come with their own unique quirks.

It’s worth noting that tags are one of a handful of structural components in a PDF. While they are probably the most important for accessibility, they need to play nicely with the structure at play at the Content level. While slightly irrelevant to this discussion, it’s also worth a reminder that tagged PDF in PDF 1.71 is described in §10.7, pg. 841; standard tags described in §10.7.3, pg. 898.

Simply retagging things in the Tags panel

This is the safest bet, but it assumes that a: the document is already tagged (just incorrectly), and b: the items that need to be retagged are already grouped properly at the container level. If the document is untagged, and no source is available from which to generate a(n improperly, even) tagged document, then the Accessibility menu has an option to ‘Add Tags to Document’. I would only do this on a backup copy, and would give the document a good once-over to make sure fixing its decisions isn’t more work than starting from scratch with one of the two options below. On short documents, starting from scratch is often quicker, I find. On longer or more complicated ones, not so much.

At any rate, changing tags in the Tags panel is generally quite quick, especially with a working knowledge of what the standard tags actually are. There aren’t a ton of obvious keyboard shortcuts, but a while back I wrote about important ones that help me speed through the process. While items that need to be broken up at the container level need a different approach, it is worth keeping in mind that often several containers will have ended up in one tag, and these can freely be moved about.

The key advantage to this method, aside from speed, is that it does not touch things as far as the Content panel is concerned. This is very important; it means you’re only fixing stuff in one panel instead of hopping back and forth between two (which can generally be achieved quickly with the respective panel’s ‘Show in [other] Panel’ option, but still).

The Touch Up Reading Order tool

A graphical approach wherein one rectangularly wraps objects and tags them via dialog box or contextual menu, this tool has the added benefit of theoretically reordering the reading order of things. Reading order in PDF is complicated, and based on Content order and Tag order. The Touch Up Reading Order tool affects the Content order, which means it moves stuff around on the Z plane. If you have background items like solid blocks of color, using the Touch Up Reading Order tool on text above it is likely to hide it underneath. Then you need to reorder these elements manually in the Content panel.

Other than that, it generally works well. If you’re dealing with straightforward text that doesn’t overlap any graphical elements, you’re unlikely to run into issues with this tool. Even if I’m not using it, I generally leave this mode selected so I can get an overview of what’s tagged as what on the page itself.

Using this tool on an untagged document was what caused the aforementioned random bytes issue. The document came from Publisher, most of the bytes were non-printing. I suspect it was an encoding error. Even though tagging the document this way would have been quicker, it was unusable because of this issue. Generating tags with the ‘Add Tags to Document’ tool did not cause this problem, and I was even able to use the Touch Up Reading Order tool to fix some table issues after everything already had a base tag created. I don’t know how common this problem is (I’ve only experienced it a few times and only with documents from Publisher), but I think it’s worth noting.

Select text in document, choose ‘Create Tag from Selection’ from dropdown menu in Tags panel

This is kind of my last resort if neither of the other strategies work, or if using the Touch Up Reading Order tool would cause too much additional reordering in the Content panel. Aside from being a bit slow and clunky, this tends to cause a problem wherein it starts duplicating and nesting containers in the Content panel. Despite the tags (in the Tags panel) being correct, this still seems to cause issues when interfacing with screen readers, so generally some manual reordering of things is necessary in the Content panel. What it doesn’t seem to get wrong is reordering objects in the same way that the Touch Up Reading Order tool does, tossing text behind graphics and the like.

  1. PDF 1.7 was the first release as an ISO standard. Adobe keeps doing their own shit, and now the PDF Association has kept the motion going with PDF 2. Adobe is still working off of PDF 1.7, adding proprietary garbage onto this standard, presumably because opening the format up was a complete farce to them. PDF 2, while a good standard, faces difficulty with adoption, by my observations. Despite being an ISO standard, PDF 1.7 is available for free PDF, and I implore everyone working with the format to read the key bits of this document. ↩︎

(Retro) Single-board computers

Single-board computers from the early microcomputing era have always fascinated me. Oft-unhoused machines resembling motherboards with calculator-esque keypads and a handful of seven-segment LEDs for a display1, their purpose was to train prospective engineers on the operations of new microprocessors like the Intel 8080 and MOS 6502. Some, like MOS’s KIM-1 were quite affordable, and gave hobbyists a platform to learn on, experiment with, and build up into something bigger.

The KIM-1 is, to me, the archetypal single-board. Initially released by MOS and kept in production by Commodore, it had a six-digit display, 23-key input pad, 6502 processor, and a pair of 6530 RIOT chips. MOS pioneered manufacturing technology that allowed for a far higher yield of chips than competitors, making the KIM-1 a device that hobbyists could actually afford. I would love to acquire one, but unfortunately they are not nearly as affordable these days, often fetching around $1,000 at auction. Humorously, clones like the SYM-1 that were far more expensive when they were released are not nearly as collectable and sell at more reasonable rates. Even these are a bit pricy, however, and you never know if they’ll arrive operable. If they do, it’s a crapshoot how long that will remain true.

Other notable single-boards like the Science of Cambridge (Sinclair) MK14 and the Ferguson Big Board rarely even show up on eBay. The MK14 is another unit that I would absolutely love to own – I have a soft spot for Clive Sinclair’s wild cost-cut creations. This seems extremely unlikely, however, leaving me to resort to emulation. Likewise for the KIM-1, a good emulator humorously exists for the Commodore 64.

History has a way of repeating itself, I suppose, and I think a lot of that retro hobbyist experience lives on in tiny modern single-board computers like the Raspberry Pi and Arduino. I’m glad these exist, I’d be happy to use one if I had a specific need, but they don’t particularly interest me from a recreational computing perspective. Given that these modern descendants don’t scratch that itch, and the rarity and uncertainty of vintage units, I was very excited to recently stumble across Thai engineer Wichit Sirichote’s various single-board kits for classic microprocessors. Built examples are available on eBay. The usual suspects are there: 8080, 8088, 8086, Z80, 68008, 6502; some odd ducks as well like the CDP1802.

I have ordered, and plan to write about the cheapest offering: the 8051 which sells in built form for $85, shipped from Thailand. The 8051 was an Intel creation for embedded/industrial systems, and is an unfamiliar architecture for me. If it all works out how I hope it will, I wouldn’t mind acquiring the 6502, Z80, CDP1802 and/or one of the 808xs. I’d love to see a version using the SC/MP (as used in the Cambridge MK14), but I’m not sure there are any modern clones available2. For now, I will do some recreational experiments with the 8051, perhaps hitting a code golf challenge or two. While this can’t be quite the same as unboxing a KIM-1, I love that somebody is making these machines. And not just one or two, but like… a bunch. Recreational computing lives.

  1. I guess machines like the Commodore 64 were technically single-board, lacking internal expansion mechanisms. But I’ve only really heard people referring to the training devices as such. ↩︎
  2. I’ve done a small amount of searching, and… there don’t seem to be. And original chips fetch $$$ at auction. Which is a real shame, because the SC/MP was a very early chip that supported, in some sense, multiple processors. That would be very, very neat to fuck with. ↩︎

MINOL and the languages of the early micros

When I started playing with VTL-2, another small and obscure language was included in the same download: MINOL. Inspired by BASIC syntax and written by a high-schooler in 1976, it “has a string-handling capability, but only single-byte, integer arithmetic and left-to-right expression evaluation.” What I am assuming is the official spec PDF was seemingly submitted over several letters to and subsequently published by the magazine, “Dr. Dobb’s Journal of Computer Calesthenics and Orthodontia.” This article described the purpose and syntax of the language, as well as the code for the Altair interpreter.

MINOL has 12 statements: LET, PR(int), IN(put), GOTO, IF, CALL, END, NEW, RUN, CLEAR, LIST, and OS (to exit the interpreter).As quoted above, there is integer arithmetic (+-*/), and there are three relational operators, =, <, and the inexplicably-designated # for not equal. Line numbers are single-byte, with a maximum of 254 lines. Statements can be separated with a colon. Exclamation points are random numbers. If (immediately) running a line without a line number, GOTO calls its line number 0. Rudimentary string-handling seems to be the big sell. This basically entails automatically separating a string into individual code points and popping them into memory locations, as well as some means of inverting this process. An included sample program inputs two strings and counts the number of instances of the second string in the first; being a bunch of code points contiguous in memory, it is certainly functional.

Is MINOL interesting, as a hobbyist/golf language? I may very well try one or two string-based challenges with it. Its limitations are quirky and could make for a fun challenge. I think more than anything, however, I’m just fascinated by this scenario that the Altair and similar early micros presented. Later micros like the Commodore PET booted right into whatever version of BASIC the company had written or licensed for the machine, but these early micros were very barebones. Working within the system restrictions, making small interpreters, and designing them around specific uses was a very real thing. It’s hard to imagine languages like MINOL or VTL-2 with their terse, obscure, limited syntaxes emerging in a world where every machine boots instantly into Microsoft BASIC.

Once again, I don’t know how much value there is in preserving these homebrew languages of yore, but as I mentioned when discussing VTL-2, folks nowadays generate esoteric languages just to mimic Arnold Schwarzenegger’s speaking mannerisms. Given that climate, I think there’s a pretty strong case to keep these things alive, at least in a hobbyist capacity. And given the needs of early micro hobbyists, I find the design of these languages absolutely fascinating. I’m hopeful that I can dig up others.

Time again for anger

Hey gang, generally if I take a step back here from esoteric programming languages or video game gripes, it’s to cry through my fists at the regressions this administration is landing upon LGBTQ+ folks. Which, more of that seems to be happening this week, so that’s something; please hug your queer friends & if you’re queer hug yourself. But, in case you somehow missed it, the reproductive freedom and bodily autonomy of folks with uteri is being rapidly destroyed. This is, in two words, fucking abhorrent.

So I’m doing this thing again where, paralyzed by the news I am unable to write anything regardless, I use this space to beg you to throw a couple of bucks to some folks who need it. Like…

Stay strong. Stay angry.