Saturday, April 15, 2006

Oh What a Lucky Man

This article takes me back... or maybe brings me full circle!

Mac Geekery - Pretty-Print Manual Pages as PS, PDF, or HTML

Back in university, learning UNIX was something you had to do on your own time. Here are some commands, they're documented online in "man pages", you figure out the rest and don't be late with your assignment.

After university, it was on to IBM's documentation group for programming languages. Naturally, there was a lot of emphasis on online information. Programming languages lend themselves to hyperlinking to look up language keywords and API names.

When AIX first came out, it had an online hypertext viewer (InfoExplorer) with a whole set of rewritten UNIX documentation. But customers didn't care much for an X11 application just to look up the syntax of ls. They wanted man pages, but didn't find any. I believe the customers finally got their way.

On every UNIX-oriented project I've worked on since then, customers have griped that there weren't any man pages, or they couldn't be viewed from the desired context, or they weren't good enough. (Typically ignoring the whiz-bang online documentation tools that came with the product or OS.) I've had this gripe myself in Oracle's SQL*Plus, where 'help xyz' brings up man-style text help, but it hasn't always been installed.

Now OS X comes along, with BSD UNIX under the hood, so once again my home computer work involves periodic use of the man command. And this article is the coup de grace -- a way to get the man output into the most elaborate viewers yet, Firefox and Acrobat Reader!

To be fair, a lot of man pages are full of obvious flaws. There are some options and restrictions that were unclear when I read a man page 20 years ago... and now on OS X I see exactly the same murky text. 'man tar' and many others don't show enough examples. 'man rsync' puts the options too late on the page.

No comments: