Better Documentation

Better documentation on the web and for LibreSSL EuroBSDCon, Bucuresti, September 22, 2018 Ingo Schwarze

YellowBellied Marmot, Kananaskis, Alberta, Canada (July 2015)

> Ingo Schwarze: Better documentation — Web & LibreSSL page 2: INTROI Bucuresti, September 22, 2018 The context of this talk Ioccasionally present updates on documentation tools at BSD conferences. General reminders about documentation • Without documentation, code is unusable, and bad documentation is about as bad as bad code. • Documentation must be correct, complete, concise, all in one place, marked up for display and search, easy to read, and easy to write. • All BSD projects use the mdoc(7) markup language because it is by far the best language available: concise, simple, providing the right amount of semantic markup. Thanks to Cynthia Livingston. (USENIX, UC BerkeleyCSRG 1990 to 1994) texinfo(1) and DocBook are excessively complicated, ill-designed, and unmaintained, DocBook also buggy as hell and sluggish; man(7), perlpod(1), and markdown provide no semantic markup. • All BSD projects use the mandoc(1) toolbox because it is functional, free (no GPL), lightweight (no C++ or XML), portable, small, and fast. Five input formats, ﬁveoutput formats, twoconverters, very powerful searching, all integrated. • See my presentation at EuroBSDCon 2015 regarding howmandoc(1) became the standard toolbox. (and those at BSDCan 2011, 2014, and 2015, too)

1:20 → 14:03:20 BSDCan 2018 p. 2 Table of contents → < > Ingo Schwarze: Better documentation — Web & LibreSSL page 3: INTROIIBucuresti, September 22, 2018 The plan for this talk Three selected topics from the manythings that were done with mandoc in 2016–2018

1. Use the strength of mdoc(7): Manual pages on the web. 2. Easily cope with language design from hell: The markdown output mode. 3. Document the inscrutable: LibreSSL and API design.

4. Other progress with mandoc in 2016-2018: • Whywedeleted SQLite from the OpenBSD base system. • Improvements for manual pages in ports. • Aim for perfection: the small things matter. 5. Summary: Paris, Sacré-Cœur (2017) Completed and open tasks. Mandoc adoption.

1:00 → 14:04:20 BSDCan 2018 p. 3 What about manual pages on the web? → < > Ingo Schwarze: Better documentation — Web & LibreSSL page 4: MAN.CGI I Bucuresti, September 22, 2018 Choice of HTML elements About ten important improvements to HTML/CSS output and man.cgi(8) were implemented in 2016–2018 alone. • Traditionally,man.cgi(8) emitted almost no tags except “”and “”; look at the HTML source code of the NetBSD online manual pages (eventoday). That’sbad because HTML is intended to provide content, marked up for its function in the respective context — not presentation, which is the job of CSS. • Mandoc nowselects adequate HTML elements depending on mdoc(7) macros, for example: (2017 Jan 19 to 2018 May 8) • .Fl .Cm .Ic .Fo.In .Fd .Cd → “” • .Dv .Ev .Er → “” • .Ar .Fa.Ft .Vt .Va → “” • .Xr .Sx .Lk .Mt → “” • .Sh → “

” • .Ss → “” → • .Rs “” Ottawa,Foreign Affairs (2018) • Some mdoc(7) macros do not have corresponding HTML elements, so theyuse generic HTML elements, for example: (2018 May 20) • .Pa.St .An → “” • .Nd → “” 1:30 → 14:05:50 NEW Howtodecide on presentation? → < > Ingo Schwarze: Better documentation — Web & LibreSSL page 5: MAN.CGI II Bucuresti, September 22, 2018 Select presentation by class • Yousee that mdoc(7) is much more speciﬁc than HTML, manymdoc(7) macros end up with the same HTML elements, evensome that require quite different presentation, for example .Fl (wants bold) and .Ev (typewriter) → “”. • Consequently,the information from the mdoc(7) macro has to be savedina “class=”attribute, and the CSS code has to select the presentation by class rather than by element type. • Also note that browsers render “”intypewriter font by default, but manymacros resulting in “”require bold font instead. • Both of the previous items require always having CSS or the presentation will look very wrong. If and (since 2018 May 1) only if no external stylesheet is provided with the mandoc(1) “-O style=”command line option, embed a minimal stylesheet in the “”element using the “