Originally Published: Saturday, 11 September 1999 Author: Michael P. Hall
Published to: featured_articles/Featured Articles Page: 1/1 - [Printable]

I Love Man Pages

When I was a young Ultrix user and lonely philosophy major adrift in a cluster full of VT100's, armed only with a beige piece of paper bestowed on me by a smirking help desk creep, the most useful and revelatory words ever revealed to me by any piece of beige paper manifested themselves:...

   Page 1 of 1  

When I was a young Ultrix user and lonely philosophy major adrift in a cluster full of VT100's, armed only with a beige piece of paper bestowed on me by a smirking help desk creep, the most useful and revelatory words ever revealed to me by any piece of beige paper manifested themselves:

Many of the commands in Unix are documented in the man pages. To read a man page about a command, type man command.

I spent the first few months of my exploration of Unix completely fascinated and awed by man pages. Man pages were, to me, representative of the sheer bigness of Unix and the industrious, earnest effort that went into so much of an operating system I was coming to love.

Man pages represented self-sufficiency that hinged on the goodwill of others, too. When I'd ask for help from someone, and they'd say, for instance, "oh, you need to use foo to do that", I knew to visit foo's man page to see what I could turn up on my own. The community was there to help with a pointer, but not to mollycoddle, or enable laziness.

It seemed at the time (and this was close to ten years ago) that nothing went un-manned, and that alone was impressive. To use a metaphor to different ends than ESR, Unix became more and more like a cathedral to me: testimony to the passion a large group of people had for something they cared about very much. It was clear that whoever was writing these pages cared about the subject and wanted other people to use the tool they'd provided. The sheer quantity of documentation spoke of many people, physically separated but sensing a larger goal.

Not being a real technical type, when I finally became aware of Linux in 1992 I wasn't really able to install it, so I soldiered on with DOS on my home computer, making batch files to simulate Unix commands, and even running Borland's Sprint as my word processor because it included Emacs key bindings.

The MS-DOS world's concept of adequate online documentation was frustrating - a command line switch that said little you couldn't figure out by just typing in a command with no parameters in most cases. I know that was fixed a little by DOS 6, but just a little. Man pages had represented the chance to behave like an autodidact in an unfamiliar environment, and they represented a genuine key to mastery -- not a frustrating enticement to go out and buy a wretched book by Que or their ilk.

Finally, three years ago, I realized I might as well rid myself of Windows and try to return to the Unix world, where things may not have been as forgiving, but my computer was a source of true joy. I found a Linux book (Patrick Volkerding's Linux Configuration and Installation, which came with Slackware) and wiped my hard drive clean. Once I'd completed the installation and had a shell prompt staring at me from the monitor, I capered around my room and blathered at my bemused roommate for 30 minutes straight about why it was unbelievably cool that at the moment, my computer was almost completely alien to me again.

Man pages were there for me again as I set about to learn how to really use Linux to do things I hadn't had to do before. Where I'd previously used Ultrix as a way to do a little text editing, enjoy some better mail clients, read Usenet, and MUD, I was now fixated on using my new Linux machine to do everything I'd used computers to do in the five years between first sitting down to a VT100 and the moment when I used fdisk to wipe my Windows partition away. I didn't want to learn how to list directories, or sort a file, or make something look tidy. I wanted the same things Microsoft and Apple claimed they had a lock on.

Sadly, though, the state of man pages in Linux was nothing like what I knew from Ultrix. The standby commands I already knew remained as documented as ever, but it seemed more and more things were referring to info; or pointing to "the documentation included in the distribution"; or advising me to type the command in with no parameters since that would tell me what I needed to know, or worse yet, (since switching to Debian earlier this year) "We know there's no man page for this, and we don't want you telling us that."

Sure, at least there's some sort of documentation, right? Of course, and I won't turn my nose up at whatever will help me learn. But in a lot of ways the very structure of man pages, thanks to their format and years of convention, had caused me to sink into a sort of receptive state when I'd consult them. Consciously or not, man page writers developed a rhythm. Over the years, when I've just completed a project that requires explaining and I've settled down to stop working and just start documenting, I've found myself sinking into the "man voice."

I also understand that the nature of Linux makes the sort of detail that goes into a man page difficult. I don't know when I last got a piece of software with a version number greater than 1 from freshmeat. So much of the Linux world is "in progress" that man pages must seem ludicrous to the authors, and some authors seem to subscribe to a brand of computer Darwinism that tells me they had very unhelpful peers during their formative years, or nurse a deep contempt for their users. Further, without an externally-derived motivator (bosses and suits), Linux frees coders to code... without feeling forced to spend time writing.

The scope of man pages first enhanced my appreciation of Unix, their detail made me a better user of tools I've come to truly enjoy, and their example has made me a more conscientious and detailed documenter of my own work. These things happened because man pages were a constant voice with consistent rules and predictable behavior. If man pages had been but one thing out of several to check during a search for answers, they'd have been less effective for me.

I hope man pages don't really go away anytime soon.

Michael P. Hall, mphall@cstone.net





   Page 1 of 1