1. 9
    1. 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.