Open Unix manual pages in OS X 10.4's Preview

Many Unix commands include relatively detailed manuals. You access these manuals using the man command, as in man cp or man ls. For simple Unix commands, reading man pages in Terminal is fine. But for anything even slightly long—or especially for something gargantuan like man bash —I find Preview to be a much better solution. You can search for words, easily scan backwards and forwards, save the whole thing as a PDF for future reference, change the zoom level of the document, and so much more. But how do you get a Unix man page into Preview? Back in the April 2004 issue of Macworld, we ran a tip in the Mac OS X Hints column that did just that. Given how useful this hint is, it’s become a routine part of my workflow whenever I need to view a man page.

In those pre-OS X 10.4 days, this required exporting the contents of (and then processing) the man page to a temporary file, then opening that temporary file in Preview. With the release of Tiger, however, the process became much simpler. So I thought I’d revisit that tip, as well as provide a very rudimentary introduction to how a profile file works in the bash shell (the default in 10.4). (If you’re still using 10.3, you’ll need to use the old solution, as detailed in this hint on macosxhints.com.)

In order to use this tip in the bash shell, you’ll need to create a function in a special file in your user’s Home directory—that’s the directory where you’ll find Documents, Movies, Pictures, etc. The special file is named .profile, and anything within it will be executed whenever you open a new Terminal window. Since its name begins with a period, it will be invisible in the Finder, though you’ll be able to see it using ls -a in Terminal. You should be able to create the file with pretty much any text editor, though you’ll probably get a warning when you try to save it under the name .profile. If you do, just acknowledge the warning and save the file anyway. (Note that future editing of this file may be a bit trickier, as your editor may or may not be able to show invisible files in the Open dialog. If that’s the case, you’ll have to use Terminal to open it— open -e .testfile will open it in TextEdit, for example.)

For today’s hint, I’ll assume you’re using whatever GUI text editor you’re most comfortable with, though this can obviously be done from Terminal using vi or nano, etc.; just make sure you create the file at the top level of your Users folder. In your editor of choice, open a new blank document and insert this code:

	pman()	{	man -t "${1}" | open -f -a /Applications/Preview.app/	}

Note that there’s a chance you may already have a .profile file—if that’s the case, then add these lines as new; don’t replace any existing lines.

The first line, pman, is the name of the command as you’ll type it to use this hint. Feel free to change it to whatever you like—shorter is better, as it means less typing. To make sure you don’t use a name of an already-existing command, open Terminal and try typing the name you’d like to use, followed by —help. The response you want to see is command not found. If you don’t see that, try another name. Once you’ve found a name you like, save your edited file with the name .profile in the top level of your Users folder.

That’s it; you’re done. Here’s what the command you just created looks like in action:

So how does this nifty command work? Well, the remainder of the lines after pman are the function that does the actual work of displaying the man pages in Preview. The open-curly-bracket marks the start of the code itself, which works like this:

man -t “${1}”: This bit calls the man application to display the page for the command you’ve asked about. The “${1}” section represents the command in question. That code tells the shell to substitute the first word you typed after pman into the command. The -t option formats the man page into PostScript.
|: This is a pipe symbol, which passes the results of the command to the left of the pipe (in this case, a PostScript formatted man page) to the command on the right, which is…
open -f -a /Applications/Preview.app/: The open -f accepts the input from the previous man command. The -a /Applications/Preview.app section tells open which program to use to do the opening.

The real tool to thank here is 10.4’s Preview, which gained the ability to read PostScript and convert it on the fly into a standard PDF document. Once the document is opened in Preview, you can do whatever you like with it—save it somewhere, print it, or just read it, find what you need, then close it—the document is created in memory only, so you don’t need to worry about leaving behind files that require later clean up.

Putting it to the test

To test your new function, open a new Terminal window, and then type pman bash (or any other command you’re interested in seeing). The bash manual is fairly sizable, so depending on the speed of your machine, you may have to wait 10 seconds or so as the command does its thing. But when it’s done, you’ll see Preview open, showing the full 60-page manual.

Enjoy your newly-formatted and easy-to-read man pages!