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!