Reading the Manual for ENIAC, the World’s First Electronic Computer
> 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.
docbook2mdoc — DocBook to mdoc converter
> 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.
Explaining Code using ASCII Art
> 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.
handy pocket guide to Unix
> printed 35 years ago and is still mostly current.
Better handle automatic column width assignments
> 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.
What nobody tells you about documentation
> 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.
You'd Need an Oracle to Understand These Docs
> 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.”
strftime's alpha-sorted man page vs. well-meaning people
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.
Early days: the VIC-20 Programmer's Reference Guide
> 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.
Reviving the 1973 Unix Programmer's Manual
> 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
Comparing the Usability of Cryptographic APIs
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.
Half a dozen new features in mandoc -T html
> 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.
New mandoc -mdoc -T markdown converter
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.
LibreSSL documentation status report
> 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.