Status update October 2020

In October, I contributed minor changes to Cute Chess.

This month marks the first year of this blog: I wrote my first status update in October 2019. You can quickly glance over all articles from the /blog page.

Cute Chess’ manuals are written in mdoc and have been since about 2012. I was using OpenBSD as my daily driver at the time, and I was dissatisfied with AsciiDoc’s man page output, so I decided to use OpenBSD’s documentation system for Cute Chess. Our main documentation target was the command-line interface of Cute Chess, cutechess-cli, so the focus was on man pages.

Mdoc is not the easiest manual system to learn. It consists of two or three letter macros of which most have semantic meaning. So instead of documenting command-line options with bold text, you document them with .Fl (for flag) and the output format handles the styling.

There are many conventions and styling nuances that need to be thought when using mdoc. For example, new sentences should begin from a new line. Well written examples are given in Practical UNIX Manuals guide.

To help new contributors write Cute Chess’ manuals and make it easier to follow the mdoc conventions I introduced manual pages checks to our continuous integration flow. The manuals are checked with mandoc -T lint and if there’re any issues found, the build will fail.

mandoc is now packaged in many distributions, such as in Debian so running the linting process does not necessarily require building mandoc from source anymore.

That’s all I have for this month, see you in the next one!