
Grapse: online man pages editor - rroperzh
http://www.roperzh.com/grapse/
======
groovy2shoes
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.

