BSDCan2011 - Final (with audio).5
BSDCan 2011
The Technical BSD Conference
| Speakers | |
|---|---|
|
Ingo Schwarze |
| Schedule | |
|---|---|
| Day | Talks - 1 - 2011-05-13 |
| Room | Tutorial |
| Start time | 16:30 |
| Duration | 01:00 |
| Info | |
| ID | 230 |
| Event type | Lecture |
| Track | Hacking |
| Language used for presentation | English |
Training a foal to replace a venerable workhorse
Mandoc in OpenBSD
The base system of OpenBSD 4.9, to be released on May 1, 2011, has the unusual property of containing a complete set of man(1) documentation without using any of the traditional troff or groff document formatting systems, neither in the installed base system nor anywhere in the build system. Instead, all documentation is formatted using the mandoc(1) utility developed by Kristaps Dzonsons. The present talk describes the decisions and processes that allowed the whole replacement project to be completed in less than one and a half years, basically by a single developer who is also working full-time on a day job.
There is consensus among OpenBSD developers that mdoc(7) remains the format of choice to produce future documentation; for some of the reasons, see the talk by Kristaps Dzonsons, "How the cart came to draw the ox: the roff tradition and mandoc". However, to ease maintenance, to reduce the dependency on C++ compilers, to reduce the dependency on GPL-licensed code, to reduce the overall code volume, and to reduce build times on slow architectures, replacing groff was desirable both for build-time and run-time rendering of base system manuals.
The task was to smoothly replace the formatting tool used to format many thousands of manuals, written by hundreds of authors using several different document generation tools, prepared and installed using several different build systems, without disrupting production use of OpenBSD-current on any architecture at any point in time, even though OpenBSD-current is rebuilt about daily for some architectures.
The problem was that, when starting the project, mandoc(1) did not even support all widely used features of the high-level mdoc(7) macro language. Even worse, manuals using the older man(7) language tend to rely on various low-level roff(7) features, and those had been deliberately excluded from the basic design of mandoc.
The talk explains how Kristaps and myself got from that challenging starting position to the reasonably groff-compatible, fully integrated mandoc we have today, processing mdoc(7), man(7), tbl(7) and a small, but relevant subset of roff(7) input, producing ASCII, PostScript, PDF, HTML and XHTML output for all manuals contained in the OpenBSD, NetBSD and FreeBSD base systems. The focus will be on the question which development approaches have proven successful, and what we learnt from those episodes where things went less smoothly.
To conclude, I'm going to report on recent trends of mandoc usage in the OpenBSD ports tree, which is a quickly moving target, and on possible future directions of mandoc development in OpenBSD.