💾 Archived View for republic.circumlunar.space › users › flexibeast › gemlog › 2021-01-19.gmi captured on 2023-05-24 at 18:12:07. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
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.
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.
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
☙
[a] In 2009, Kristaps Džonsons wrote an article for USENIX magazine comparing various languages for man pages: