I could, element by element, continue to add support (mostly by making CSS updates for each element to fit in with the rest of my style choices) as I came across specific needs for them, but not one to shy away from an exhaustive exploration, I decided to write this post and attempt to use every element.

A goal of the post, was to avoid delaying other future posts with CSS updates on a previously unused element, but in reality it took a year and a half to make all the updates for just this post! I am using the MDN Web Docs list of HTML elements as a reference which has more than 100 tags divided into a few categories, which I will also use in this post.

source: L

I went through some of the examples of metaphors in Metaphors To Live By and grepped all the man pages on my computer for them.

It seems like the machine was temperamental. For example, it warns that the DC power should never be turned on without first turning the operation switch to “continuous.”

“Failure to follow this rule causes certain DC fuses to blow, -240 and -415 in particular.”

But the consequences are even worse if you opened the DC fuse cabinet when the D.C. power was turned on. “This not only exposes a person to voltage differences of around 1,500 volts but the person may be burned by flying pieces of molten fuse wire” (if one of the fuse cases suddenly blew). In fact, the ENIAC was actually designed with a door switch shunt that prevented it from operating if one of its panel doors was open, “since removing the doors exposes dangerous voltage.” But this feature could be bypassed by holding the door switch shunt in its closed position.

The docbook2mdoc utility is a converter from DocBook version 4.x and 5.x XML to mdoc. Unlike most DocBook utilities, it’s a standalone ISC-licensed ISO C utility with no external dependencies that should compile on any modern UNIX system.

docbook2mdoc is no longer experimental, but many features are likely to still be missing, and the rendering of many elements is not ideal yet. However, it can already be used for production purposes and was tested on parts of the OpenGL and X.Org DocBook corpuses.

People tend to be visual: we use pictures to understand problems. Mainstream programming languages, on the other hand, operate in an almost completely different kind of abstract space, leaving a big gap between programs and pictures. This piece is about pictures drawn using a text character set and then embedded in source code. I love these! The other day I asked around on Twitter for more examples and the responses far exceeded expectations (thanks everyone!). There are a ton of great examples in the thread; here I’ve categorized a few of them. Click on images go to the repositories.

printed 35 years ago and is still mostly current.

Modified files:
usr.bin/mandoc : out.c

Log message:
Better handle automatic column width assignments in the presence of horizontal spans, by implementing a moderately difficult iterative algoritm. The benefit is that spans containing long text no longer cause an excessive width of their starting column.

Also, use unicode for drawing: https://marc.info/?l=openbsd-cvs&m=154338047707592&w=2

And some other assorted commits that are fun.

They are: tutorials, how-to guides, explanation and technical reference. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation - often immensely.

Not 100% agreed on all points, but this is a good framework for considering what one is doing when writing.

source: L

This time, I trace through a few references, discover another footnote which is itself reference to a white paper, which itself contains a footnote. “If cogs_behavior is set,RM_CONS_BY_UT,RM_CONS_IN_FRMLU_FPT,RM_CALC_FRMLUandCOGS_RM_CALC_USAGE may alter data in an unrecoverable fashion.”

Alpha sorting is still probably the best option. I’m not sure how one could reasonably implement “utility” sorting. The solution perhaps is to limit the amount of stuff requiring documentation to make it easy to read.

There are all sorts of interesting parts to this book. It tells you all of the useful memory locations in a list, in addition to talking about them in prose. This way, you can find things like what location in memory controls the screen’s border color, or the background color. You can figure out which locations drive the different parts of the sound chip.

Here you can find the manual in PDF format. As is the case with all the original Unix documentation, its quality in terms of conciseness, completeness, and rigour remains unsurpassed until today

Experimentally testing APIs by making developers write code and examining their mistakes. Turns out what’s easy and what’s hard makes a difference. Also, documentation matters. I don’t think the result is surprising, but instead is concrete reinforcement that this stuff can be tricky.

The HTML output mode of mandoc(1) just grew a couple of new features. I’m providing this short summary because it’s all user-visible and might make using the online manuals easier.

mandoc can output markdown, and you can read Ingo’s thoughts on the matter.

The reason for providing this output mode is not that i consider markdown a good, or even a half-decent, markup language. Quite to the contrary, I hereby offcially declare it the shittiest markup language i have seen so far. Basically, it hasn’t any strong point whatsoever, but the downsides are numerous, scary, and cover practically every relevant aspect:

So even though this is the first release in the 1.14 branch, i consider the code very solid by now and call it 1.14.1 rather than 1.14.0.

SVG images to illustrate common crypto operations, including happy and sad Alices.

For at least some images though, Firefox has trouble drawing within the lines.

The short term goal is to make sure that LibreSSL documentation becomes better than OpenSSL documentation. Not merely better on average, but better in any conceivable respect.

Documentation change, to reflect reality.