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:

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]