.\" .\" Copyright (c) 2018 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this presentation for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE PRESENTATION IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL .\" WARRANTIES WITH REGARD TO THIS PRESENTATION INCLUDING ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA .\" OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS PRESENTATION. .\" .\" -------------------------------------------------------------------- .\" .\" These slides use the mm and gpresent groff macros. .\" For example, on OpenBSD, install these ports: .\" groff, gpresent, ghostscript. .\" .\" Build instructions: .\" groff -st -mm -mpresent talk.roff > talk.pps .\" presentps -l talk.pps > talk.ps .\" ps2pdf talk.ps .\" .\" --- global mm configuration settings ------------------------------- .nr Pi 3 .\" --- global gpresent configuration settings ------------------------- .DEFCOLOR Kea1 0 0.8 0.48 .DEFCOLOR Kea2 0 0.5 0.3 .TITLECOLOR Kea1 .SUBTITLEFORMAT C .SUBTITLECOLOR Kea2 .FOOTERSIZE 2 .\" We don't want a header line for the title page, .\" so we have to start it before setting up headers. .TITLE "Better documentation" .\" === gpresent header setup ========================================== .\" --- define gpresent extension registers ---------------------------- .nr gpe_page_tot 1 .nr gpe_page_sec 0 .af gpe_page_sec I .nr gpe_dur_min 0 .nr gpe_dur_sec 0 .af gpe_dur_sec 02 .nr gpe_time_tsec 14*60+2*60 .nr gpe_time_hour 14 .nr gpe_time_min 2 .af gpe_time_min 02 .nr gpe_time_sec 0 .af gpe_time_sec 02 . .\" --- macro to start a new section ----------------------------------- .de GPE_SECTION .ds gpe_title_sec \\$1 .nr gpe_page_sec 0 .. .\" --- macro to prepare a new page ------------------------------------ .de GPE_NEXT .ds gpe_next \\$1 .SK .. .\" --- gpresent page header callback ---------------------------------- .de HEADER .nr gpe_page_tot +1 .nr gpe_page_sec +1 .sp 0.5v .ds gpe_middle page \\n[gpe_page_tot]: \\*[gpe_title_sec] \\n[gpe_page_sec] .tl 'Ingo Schwarze: Better documentation \(em Web & LibreSSL'\ \\h'2c'\\*[gpe_middle]'\ Bucuresti, September 22, 2018' .sp -0.5v .\" horizontal line below the page header \l'\\n(.lu'\h'-\\n(.lu' .br .. .\" --- initialize the first section before completing the title page -- .GPE_SECTION INTRO .\" === define some gpresent extension macros ========================== .\" --- line length ---------------------------------------------------- .\" To return to full line length after temporarily reducing it. .nr gpe_ll \n(.l .\" --- emphasis ------------------------------------------------------- .de GPE_EM .COLOR red \\$1\c .COLOR P \&\\$2 .. .de GPE_OK \Z'\\$1'\m[red]\l'\w"\\$1"u\(mi'\m[] \m[Kea2]\(OK\m[]\\$2 .. .\" --- small text ----------------------------------------------------- .de GPE_SM .S -4 \\$1 .S P .. .\" --- quoted literals ------------------------------------------------ .de GPE_QL \(lq\f(CW\\$1\fP\(rq\\$2 .. .\" --- tweak -mpresent macros ----------------------------------------- .\" Reduce vertical spacing by the given argument. .\" Can only be called right after .SP with a larger argument. .de GPE_SPM .sp -\\$1 .nr line*ac\\n[.z] -\\$1 .nr line*lp\\n[.z] \\n[.d] .. .am TITLE .GPE_SPM 0.1i .. .am SUBTITLE .GPE_SPM 0.05i .. .de INACTIVE_TITLE .TITLECOLOR violet .TITLE \\$* .TITLECOLOR Kea1 .. .\" --- title page ----------------------------------------------------- .\" The main title line has already been printed. .sp -1v .SUBTITLE "on the web and for LibreSSL" .SUBTITLE "EuroBSDCon, Bucuresti, September 22, 2018" .SUBTITLE "Ingo Schwarze " .sp -0.5v .PSPIC Images/YellowBelliedMarmot2.eps .ce .GPE_SM "Yellow Bellied Marmot, Kananaskis, Alberta, Canada (July 2015)" .\" === gpresent footer setup ========================================== .\" We dont want a footer line for the title page, .\" so we have to set it up after completing the title page. .SK .\" --- macros to start a new page ------------------------------------- .\" arg: time for this page in seconds .de GPE_TIME .nr gpe_dur_min \\$1/60 .nr gpe_dur_sec \\$1%60 .nr gpe_time_tsec +\\$1 .nr gpe_time_hour \\n[gpe_time_tsec]/3600 .nr gpe_time_min \\n[gpe_time_tsec]%3600/60 .nr gpe_time_sec \\n[gpe_time_tsec]%60 .ie '\\$2'' .ds gpe_source NEW .el .ds gpe_source BSDCan 2018 p. \\$2 .. .\" --- gpresent page footer callback ---------------------------------- .de FOOTER .ps 18 .vs 20 .sp -2v \l'\\n(.lu'\h'-\\n(.lu' .br .tl '\s-6\\n[gpe_dur_min]:\s-2\\n[gpe_dur_sec]\s+2 \(->\ \\n[gpe_time_hour]:\\n[gpe_time_min]:\s-2\\n[gpe_time_sec]\ \\*[gpe_source]\s+8''\\m[Kea2]\\*[gpe_next]\ \ \(->\\m[]' .ps .vs .. .\" The INTRO section was already started in header.roff. .TITLE "The context of this talk" .ce I occasionally present updates on documentation tools at BSD conferences. .SUBTITLE "General reminders about documentation" .BL .LI .GPE_EM "Without documentation, code is unusable," .br .GPE_EM "and bad documentation is about as bad as bad code." .LI Documentation must be correct, complete, concise, all in one place, .br marked up for display and search, easy to read, and easy to write. .LI All BSD projects use the .GPE_EM "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. .GPE_SM "(USENIX, UC Berkeley CSRG 1990 to 1994)" .P .GPE_SM "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." .LI All BSD projects use the .GPE_EM "mandoc(1)" toolbox because it is functional, .br free (no GPL), lightweight (no C++ or XML), portable, small, and fast. .br Five input formats, five output formats, two converters, .br very powerful searching, all integrated. .LI See my presentation at EuroBSDCon 2015 regarding how mandoc(1) became .br the standard toolbox. .GPE_SM "(and those at BSDCan 2011, 2014, and 2015, too) .LE .GPE_TIME 80 2 .GPE_NEXT "Table of contents" .TITLE "The plan for this talk" .ce 2 .GPE_EM "Three selected topics" from the many things that were done with mandoc in 2016\(en2018 .sp .mk .BVL 1c .LI "1. Use the strength of mdoc(7):" Manual pages on the .GPE_EM web . .LI "2. Easily cope with language design from hell:" The .GPE_EM markdown output mode. .LI "3. Document the inscrutable:" .GPE_EM LibreSSL and API design. .sp .LI "4. Other progress with mandoc in 2016-2018:" .BL .LI Why we deleted SQLite .br from the OpenBSD base system. .LI Improvements for manual pages in ports. .LI Aim for perfection: the small things matter. .LE .LI "5. Summary:" Completed and open tasks. Mandoc adoption. .LE .rt .PSPIC -R Images/Paris17_SacreCoeurClocher.eps .rj .GPE_SM "Paris, Sacr\('e-C\(oeur (2017)" .GPE_TIME 60 3 .GPE_SECTION MAN.CGI .GPE_NEXT "What about manual pages on the web?" .TITLE "Choice of HTML elements" About ten important improvements to HTML/CSS output and man.cgi(8) .br were implemented in 2016\(en2018 alone. .BL .LI Traditionally, man.cgi(8) emitted almost no tags except .GPE_QL and .GPE_QL ; look at the HTML source code of the NetBSD online manual pages (even today). .br That's bad because HTML is intended to provide content, marked up for its function in the respective context \(em not presentation, which is the job of CSS. .LI Mandoc now selects adequate HTML elements depending on mdoc(7) macros, for example: .mk .GPE_SM "(2017 Jan 19 to 2018 May 8)" .BL \n(Pi compact .LI \&.Fl .Cm .Ic .Fo .In .Fd .Cd \(-> .GPE_QL .LI \&.Dv .Ev .Er \(-> .GPE_QL .LI \&.Ar .Fa .Ft .Vt .Va \(-> .GPE_QL .LI \&.Xr .Sx .Lk .Mt \(-> .GPE_QL .LI \&.Sh \(-> .GPE_QL

.LI \&.Ss \(-> .GPE_QL

.LI \&.Rs \(-> .GPE_QL .LE .LI Some mdoc(7) macros do not have corresponding HTML elements, .br so they use generic HTML elements, for example: .GPE_SM "(2018 May 20)" .BL \n(Pi compact .LI \&.Pa .St .An \(-> .GPE_QL .LI \&.Nd \(-> .GPE_QL
.LE .LE .rt .sp -0.5v .PSPIC -R Images/Ottawa18_Diefenbaker.eps .rj .GPE_SM "Ottawa, Foreign Affairs (2018)" .GPE_TIME 90 .GPE_NEXT "How to decide on presentation?" .TITLE "Select presentation by class" .sp -0.5v .BL .LI You see that mdoc(7) is much more specific than HTML, many mdoc(7) macros end up with the same HTML elements, even some that require quite different presentation, for example .Fl (wants bold) and .Ev (typewriter) \(-> .GPE_QL . .LI Consequently, the information from the mdoc(7) macro has to be saved in a .GPE_QL class= attribute, and the CSS code has to select the presentation .GPE_EM "by class" rather than by element type. .LI Also note that browsers render .GPE_QL in typewriter font by default, but many macros resulting in .GPE_QL require bold font instead. .LI Both of the previous items require .I always having CSS or the presentation will look very wrong. If and .GPE_SM "(since 2018 May 1)" .I "only if" no external .GPE_EM stylesheet is provided with the mandoc(1) .GPE_QL "-O style=" command line option, embed a minimal stylesheet in the .GPE_QL element using the .GPE_QL