Contributed by phessler on from the may-the-schwarze-be-with-you dept.
The mdoc(7) language can now easily be used to document portable software
Whenever possible, people want to write documentation using the modern, nice, structured BSD mdoc(7) language and not using the dated, ugly, low-level UNIX man(7) language. However, some archaic operating systems like Solaris still do not ship with an mdoc(7) formatter - a fact that is easy to understand when you consider that mdoc(7) was only invented quite recently: It first appeared in 4.4BSD, released in June 1993,
which is less than twenty years ago.
Hence, a few years back, millert@ wished for an mdoc(7) to man(7) converter such that he can write and maintain the sudo(8) manuals using the mdoc(7) language, automatically convert them to man(7), and include both versions into the portable distribution tarballs, such that modern systems like OpenBSD can use the mdoc(7) versions and ancient ones like Solaris can use the man(7) versions.
As a part of the mandoc(1) project, i set out to write that converter, to be invoked as mandoc -Tman, in September/October 2011, around the p2k11 Budapest ports hackathon. In July 2012, during the g2k12 Budapest general hackathon, i did the bulk of the work on that converter, implementing the missing macros An, Bf, Bk, In, Ec, Eo, Fa, Fd, Fo, Fn, Ft, Lk, Mt, No, Sm, Va, Vt, and the missing parts of Bd, Bl, It, Lb, Nm, and Rs; a side effect was finding and fixing several bugs in the common mdoc(7) parser and in the default mandoc -Tascii output mode as well.
At that point, the mandoc -Tman converter was pretty much usable - so much that on July 20, 2012, millert@ played the Guinea pig, including manuals written in the mdoc(7) language in the portable sudo 1.8.6b3 beta release for the first time, together with versions converted to man(7) using OpenBSD-current mandoc(1) enhanced with a small set of patches of his own.
Due to the general strike in Portugal on November 14, 2012 - no complaint, i hope this movement will become even stronger and even more successful! - the Coimbra hackathon was considerably shorter than most other hackathons for me, basically it was barely four days of hacking.
Still, that was sufficent to:
- Integrate the last of the patches provided by millert@, generalizing a part of them; the first bunch had already been integrated during the summer.
- Make the SYNOPSIS section imply automatic word keep (Bk) mode in -Tman, just like in -Tascii, as requested by millert@.
- Fix a crash caused by malformed tag lists reported by florian@.
- Improve formatting of badly nested font blocks, which is technically a somewhat similar issue.
- Fix various formatting issues reported by Nicolas Joly that he found doing systematic groff-mandoc output comparisons using the complete set of NetBSD base system manuals.
- Cleanup variable naming in part of the mandoc(1) code base to help reading the code and reduce the risk of confusion.
So for me, this was a somewhat unusual hackathon as there wasn't a very clear focus - or rather, the focus was finishing and polishing this and that all over mandoc(1). And, of course, comer peixe and enjoying the very nice city of Coimbra. In that sense, Pedro, Luis, Rodolfo and Bob: So long, and thanks for all the fish!
(Comments are closed)