|
December 2003
The Open Road: Creating your own man pages
Over the years I've accumulated dozens of books on Linux and Unix, but none of these books has ever come in as handy as the man pages that document system commands and other important aspects of *nix systems.
To close out 2003, I thought I'd discuss man pages and how to write your own man pages. Most, but not all, programs distributed for *nix systems come with their own man pages — so it's rare that you'll have to write man pages for popular applications and programs. I have found a few exceptions, though, and the Debian Project maintains a list of needed man pages. You can also check out the Missing Man Pages Project (m2p2) if you're interested in contributing.
It's not uncommon for an organization to use applications that are not documented with man pages — or indeed documented in a meaningful form at all. However, it's a good idea to maintain documentation for in-house applications and such, and to train users to actually utilize man pages if they're using *nix systems. By the way, if your users prefer to access documentation via a company Intranet, you can use man2html to convert man pages to HTML. I'll cover this as well. If you're really into online documentation, you could even use man to create documents for things like the company phone directory or policy manual. (In fact, a man page stating the organization's computer usage policy might not be a bad idea...)
Let's look at the anatomy of a man page first, and then walk through the creation of a simple man page.
|
