When Kristaps Dzonsons set out to write mandoc in the fall of 2008, all he wanted was a nicer HTML representation of manual pages on his private website. Today, mandoc is the standard manual page formatter in OpenBSD, FreeBSD, NetBSD, DragonFly, illumos, and Void Linux, and OpenBSD also uses it as the manual page viewer man(1), as the manual page search tool apropos(1)/makewhatis(8), and as man.cgi(8) to search and display manual pages on the web. It now produces ASCII, UTF-8, HTML5, MathML, PostScript, PDF, and man(7) output. Given that manual page toolkits existed for almost four decades before Kristaps even started, how could such an overfulfillment of expectations possibly happen, and what lessons were learnt in the process?
Topics of this meeting include:
– importance of and requirements for software documentation
– history of roff/man/mdoc, and why they remain the best doc tools
– features of mandoc, both seasoned and new ones
– mandoc development and system integration, or how to lead a software package to success
– mandoc adoption in various operating systems and possible future directions
The talk is designed as a best-of selection of content shown at BSDCan 2011, 2014 and 2015 and EuroBSDCon 2014.
After the presentation, you are welcome to optionally stay for a hands-on workshop, so be sure to bring your notebook. You might wish to hunt for markup bugs in operating system manuals, or you might wish to work on format conversions from legacy formats to mdoc(7), and if you already have some experience, there are more ideas, see for example pages 40-43 of http://www.openbsd.org/papers/eurobsdcon2014-mandoc-paper.pdf.
In any case, there is a chance to do some work that results in your first commit into your favourite operating system – that did happen at a similar workshop held at EuroBSDCon 2014 in Sofia/Bulgaria…
Ingo Schwarze is the current maintainer of the mandoc(1) documentation toolbox developed by Kristaps Dzonsons. He also maintains the OpenBSD groff(1) port and has contributed to various parts of the OpenBSD userland, for example the Perl rewrite of the security(8) script, as well as smaller contributions to the rc.d(8)/rcctl(8) framework, the yp(8) subsystem, the C library, and various other programs.
After studying in Siegen (supervisor: Prof. Martin Holder), Ingo Schwarze worked in experimental and theoretical high energy physics at CERN (NA48) and in Karlsruhe. Having used various flavours of UNIX and Linux in the nineties, he settled on OpenBSD as his server and desktop operating system of choice in 2000 and joined the project as a developer in the spring of 2009. As a day job, he maintained the central configuration daemon and the MiddleWare of the Astaro Security Gateway (now called Sophos UTM) for six years.