I’m surprised there wasn’t a “technical writing” tag or similar.
I’m looking at mdoc to generate man pages and an html page for sr, my spaced repetition program. I think having a manual page locally accessible is great and consistent formatting is even better. Makes me wonder actually why more haven’t adopted this or extended it carefully…!
My impression is that many projects use the -man macro package because … many other projects use the -man macro package. For example, the Linux man-pages project:
New manual pages should be marked up using the groff an.tmac package described in man(7). This choice is mainly for consistency: the vast majority of existing Linux manual pages are marked up using these macros.
Which is a shame, because they suck. They’re harder to write, make for uglier source code, and have worse output.
The BSD folks have seen the light, though. Take a look at their manual pages for role models. No SCREAMING_CASE_FOR_EVERY_ARGUMENT; synopses that help you use the program; typographically correct ‘’ curly quotes instead of straight quotes or, god forbid, ` and '.
I’m surprised there wasn’t a “technical writing” tag or similar.
I’m looking at mdoc to generate man pages and an html page for
sr, my spaced repetition program. I think having a manual page locally accessible is great and consistent formatting is even better. Makes me wonder actually why more haven’t adopted this or extended it carefully…!My impression is that many projects use the
-manmacro package because … many other projects use the-manmacro package. For example, the Linuxman-pagesproject:Which is a shame, because they suck. They’re harder to write, make for uglier source code, and have worse output.
The BSD folks have seen the light, though. Take a look at their manual pages for role models. No SCREAMING_CASE_FOR_EVERY_ARGUMENT; synopses that help you use the program; typographically correct
‘’curly quotes instead of straight quotes or, god forbid,`and'.It’s hard to go back.