flexibeast.space - gemlog - 2021-01-19
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].
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.
☙
☙
[a] In 2009, Kristaps Džonsons wrote an article for USENIX magazine comparing various languages for man pages: