Writing man Pages

Here are a few resources for those among you thinking of writing proper documentation for your new project, or to contribute writings or translations to your favorite Community.

Man pages are written in Troff, the original UNIX typesetting system. Nowadays, few people (most notably man page writers and IETF RFC authors) regularly use this markup, but it is rather simple and elegant once you get to know it. For writing man pages, the learning curve is very good, as you only need to know a few macros and, just as if you were working on html and pilfering the sources of an existing page doing just what you need, you have a wealth of examples to teach you right there on your trusty *NIX box. As the Wikipedia points out:

Troff features commands to designate fonts, spacing, paragraphs, margins,
footnotes and more. Unlike many other text formatters, troff can position
characters arbitrarily on a page, even overlapping them, and has a fully
programmable input language. Separate preprocessors are used for more
convenient production of tables, diagrams, and mathematics.

But you don’t need to master all that! For Linux man pages, what you need is knowledge of the man macro package, written by James Clark and documented in man(7) or groff_man(7) depending on your distro. Troff input is processed from text files, so you just need your favorite text editor, and a bit of time to play with the markup to learn it in the process.

Here is a way to get started quickly: Linux Journal published a great tutorial a few years back, and the Linux Manual contains the ever-important style guidelines in man-pages(7). Start from scratch, or make a copy of an existing manual page and start editing. One more tip for you:

man ./foo.1

is your friend, to see what you just wrote and marked up in all its glory — and bugs.

WEB RESOURCES #

Linux Journal: Writing man Pages Using groff
The Linux Manual: man-pages(7)
The Linux Manual: man(7)

BOOKS #

Arnold Robbins, Nelson Beebe, Classic Shell Scripting (O’Reilly – 9780596005955) – Appendix A “Writing Man Pages” is for you.
Dale Dougherty, Tim O’Reilly, Unix Text Processing (out of print, released in the public domain) – all the Troff you could ever want, but not the man macros.

UPDATE: Technical Report 54 of Bell Labs was the original Troff Manual: Joseph Ossanna, Brian Kernighan, Troff User’s Manual (Computing Science Technical Report No. 54).

Cross-posted to OpenSUSE Lizards.