For people who want to learn how to write man pages, I've found the following resources to be invaluable: "Practical UNIX Manuals: mdoc" - an introduction to w

For people who want to learn how to write man pages, I've found the following resources to be invaluable: "Practical UNIX Manuals: mdoc" - an introduction to writing man pages in the mdoc language (http://manpages.bsd.lv/ http://manpages.bsd.lv/) "mdoc(7)" - a definitive reference for the mdoc language (http://mdocml.bsd.lv/man/mdoc.7.html http://mdocml.bsd.lv/man/mdoc.7.html) Detailed mdoc documentation (http://mdocml.bsd.lv/mdoc/ http://mdocml.bsd.lv/mdoc/) The mandoc utility also has a built-in linter for man pages, run with -Tlint (http://mdocml.bsd.lv/ http://mdocml.bsd.lv/). It was originally designed for OpenBSD but it is portable. I've run it on Linux and Cygwin without issues. It really is an amazing tool, and its own documentation is fantastic. Users writing new man pages should prefer the mdoc language to the legacy man language. mdoc has been around for nearly two decades, works well on all modern platforms, and is a semantic markup language rather than a presentational one. If you really need to support legacy systems, mandoc can convert man pages written in mdoc to man. Please don't write man pages in Docbook or anything that relies on Docbook for man page output. I've had so many issues with xmlto and xsltproc and Docbook. Really, mdoc is very simple and writing it by hand is not a big deal. Modern man page processors can also produce HTML or PDF output, so don't worry about that. I'm sad that I've had to pull in such a heavyweight and complicated toolchain that doesn't even work half the time just to generate some tiny man pages.