Posted on November 29, 2009 at 9:38pm EST. More.

Nicer ways to view UNIX man pages

There is a wealth of information available in the UNIX manual pages, but it feels a little silly to be reading text out of a terminal window, especially since I paid so much money for all this fancy font rendering technology.

Here are some alternatives:

To view a man page in Xcode’s documentation window, simply select “Open man Page…” from the Help menu. For some reason, I hadn’t noticed that menu item until I read this hint on accessing it via AppleScript. Nicely formatted and references to other man pages are hyperlinked.

Bwana allows you to read man pages in any web browser, by registering itself as a protocol handler for man: URLs. Once installed, you can type man:perl in your browser’s address bar or open man:perl at a command prompt to read a manual page in your browser. Like Xcode, cross-references become hyperlinks, but it formats text using Courier. Source code is available, so I guess if I care enough I can do something about it.

Finally, a surprisingly short incantation will open any man page as a beautifully formatted document in Preview:

man -t perl | open -f -a /Applications/

The -t option tells man to output PostScript, and the -f option tells open to put its input into a temporary file and pass that along to the specified application.

After reading that hint I set about writing a shell function so I could type manp perl to open Perl’s manual page in Preview. However, Preview’s PostScript to PDF conversion is kind of slow, so I wound up writing something slightly more sophisticated:

function manp {
    local M=`man -w $*`               # Get path of page source.
    if [ -z $M ]; then return; fi     # Quit if it doesn't exist.
    local N=`basename $M .gz`         # Extract the name of the file and
    local P=$TMPDIR/man.$N.pdf        # use it to create a PDF file name.
    if [ ! -e $P ]; then              # If the PDF file doesn't exist,
        echo Creating PDF for $N... 
        man -t $1 | pstopdf -i -o $P  # generate it.
    open $P                           # Open the PDF version.

Then I went back and read the comments, which contain a dozen or so different versions of the same idea. But mine’s the best! Copy and paste it into the your .profile if you agree.