[talk] June 18 Special Meeting: Ingo Schwarze on Mandoc

[George Rosamond]

Thursday, June 18 Special Meeting

mandoc: from scratch to the standard BSD documenation toolkit in 6
years, Ingo Schwarze

18:45, Two Sigma, 101 6th Avenue, 23rd floor

NOTICE: Must RSVP to rsvp [at] lists [dot] nycbug [dot] org and bring ID

Abstract

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...

Speaker Bio

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.