Why i like mdoc(7) for man pages

i'm currently working on updating the man pages in my port of the s6 documentation, following a new release of s6 several days ago.

=> s6, a process supervision suite

i chose to use mdoc(7) for the port rather than than man(7) because the former emphasises semantics rather than presentation[a].

=> mdoc(7) | man(7)

i prefer a language emphasising specifying what text is, rather than how the author feels it should look, for a couple of reasons.

Facilitating presentational changes and format conversions

For example, when a program, a function and a type are all italicised, it's not trivial to determine whether italicised text is supposed to indicate a program, a function, a type, or mere emphasis. This makes it more difficult to, say, single out program names to be presented in bold, or to have particular markup for program names in a destination format.

Searches more powerful than brute-force grepping, via macro-key searching

For example, to search all man pages for mentions of the ‘foo-’ set of functions, in a situation where there are also programs named ‘foo-’, one can do:

$ apropos 'Fn~foo-'

where the ‘~’ indicates the search term is a case-sensitive extended regular expression.

=> “Macro keys for use with apropos(1)”

If you've been put off by the overall complexity of roff systems, don't assume that learning mdoc(7) is inherently difficult; i've found mdoc(7) a pleasure to learn and use.

☙

🏷 dev,documentation,ict

=> Glossary | Gemlog Home

☙

[a] In 2009, Kristaps Džonsons wrote an article for USENIX magazine comparing various languages for man pages:

=> “Fixing on a standard language for UNIX manuals” [PDF]