1. 9
  1.  

  2. 4

    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…!

    1. 1

      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 '.

      It’s hard to go back.