OVERHEAD

Acronyms

I have gone over the site, top to bottom, and added as many abbreviation elements as I thought necessary. I am very glad I did this now, instead of doing it later once I reach 100 blog posts or something; however, this still took me longer than I’d like. Worth it for the added clarity and ARIA compliance though.

When selecting text on this blog, links & abbreviations will have different background colours to the rest of the text. This should be useful when looking for links in a mass of text (don’t forget about keyboard navigation with TAB as well though).

Monospace elements

<var> elements inside code and samp are now handled properly, and <kbd> elements in samp elements are now visually distinct from neighbouring text (along with some general styling tweaks). See the ‘Heading 4’ section of the Blog Style post for how monospace elements present themselves.

Additionally, I’ve introduced variable elements inside inline code snippets where appropriate (yes, even the old CSS & Hugo posts).

I’ve chosen not to add variable elements inside <pre> elements for the time being, both because I’m uncertain of how semantically correct it’d be, and also out of shear laziness—it has taken me so damn long to get here already, please have mercy.

Semantic elements

The way I’ve interpreted the semantic meaning of HTML elements has changed over time; but now, I’ve unified how I use them as best as I could. There is one outlier though: commands.

Ambiguity around commands

The MDN website implies keyboard elements (<kbd>) are the most semantically correct element for describing commands; however, that isn’t as straightforward an answer as I’d hope because of how my blog refers to commands:

• Sometimes, I’m telling someone to run a command. In which case, <kbd>command</kbd> seems the most appropriate; it represents my expectation of what the reader should be typing.
• But sometimes, I’m simply mentioning a command without instructing anyone to use or interact with it in anyway. In which case, <code>command</code> would seem the most appropriate. I’m not expecting the reader to react, so a keyboard element feels incorrect, but a code element would convey that it’s something that a program (e.g. a shell) would understand.
• And as a bonus headache, if I tell someone to execute a command as its full filesystem path—like /usr/bin/command—then using just a keyboard element or a code element would omit key semantic information. And, there doesn’t seem to be any guidance on how you would combine these two elements in a semantically correct way.

Because of this ambiguity, and a desire to not have to special-case every use of a command based on context, I’ve decided to use code elements for all commands except within sample elements where the context is very clear (e.g. <samp>$ <kbd>command --help</kbd></samp>).

I’ve opened a GitHub issue for the WHATWG’s HTML specification to track this problem. I doubt it’ll get much traction, but at least it’s documented somewhere for anyone stumbling into this issue in the future.

Side notes

• You may of noticed that the copyright year in the footer of some posts doesn’t match the publication year. Whenever I significantly modify a post, I update the post’s lastmod field to reflect when it was modified; the copyright year is updated to reflect when a change has occurred.
• This change was committed a while ago but, in case you haven’t noticed, headings now have a bookmark icon (¶) next to them when hovered on and a hashtag icon (#) while being targeted (e.g. activate this link to the ‘Side notes’ heading to target it).
  • Previously, the headings would only change in colour when reacting to the reader’s input. This would of been very difficult for people with some forms of colour blindness to notice, e.g. achromatopsia; monochromatic vision.