atomicbird

Last year I posted a script that could be used in place of the Unix "man" command to generate PDFs of the man pages in question. If Mint is to be believed, this continues to be a fairly popular page, so here's an update on the old version.

When I posted it, Tiger (Mac OS X 10.4) was still current. After Leopard (10.5) came out I found it necessary to update the script slightly. Not because the old one didn't work, but because Leopard brought many updated man pages with it. The caching mechanism used by the script had no way to detect that the cached PDF was out of date relative to the man page it was based on.

Anyway, here's an updated version of the script. PDFs are cached, as before, but are re-generated if the cached PDF is stale.

As with the previous version, you can use it just like "man": "manpdf time" and "manpdf 3 time", for example, differ from the stock "man" command only in that a PDF is generated.

Source is below, you can also download it directly.

#!/bin/bash

# Convert man pages to PDF and open them in the default PDF viewer.
# PDFs are cached when created.
# By Tom Harrington, tph at atomicbird dot com, 16 March 2005

# Directory to save cached PDFs in 
# (if you don't want long-term caching, you could use /tmp/).
CACHEDIR=~/Library/Caches

# Command to read PS from stdin and write PDF to an output file.
PS2PDF_CMD="/usr/bin/pstopdf -i -o"
# Command to open the resulting PDF once it's created.
OPEN_CMD="/usr/bin/open"
# Path to "man", which is expected to take the -w, -S, and -t args.
MAN_CMD="/usr/bin/man"

CACHEDIR="$CACHEDIR/manpdf"
if [ ! -e $CACHEDIR ]; then
	mkdir -p $CACHEDIR
fi

if [ $# -eq 1 ]
then
	MANSECT=""
	MANARG=$1
elif [ $# -eq 2 ]
then
	MANSECT=$1
	MANARG=$2
else
	echo "Usage: " `basename $0` "[section] name"
	exit
fi

if [ "$MANSECT" != "" ]; then
	MANSECTARG="-S $MANSECT"
fi

# Look for the command's man page.
MANFILE=`$MAN_CMD $MANSECTARG -w $MANARG 2>/dev/null`
if [ -z $MANFILE ]; then
	echo No manual entry for $MANARG
	exit
fi
# OK, got the man page.  Now get the name for the corresponding
# PDF.  The goal here is to organize cached PDFs in CACHEDIR
# according to man-page section, similar to the way /usr/share/man
# is organized into "man1", "man3", etc.
echo file: $MANFILE
MANSECT=`echo "$MANFILE" | sed 's/.*\.\([0-9]\).*/\1/'`
MANPDF=$CACHEDIR/pdf$MANSECT/$MANARG.$MANSECT.pdf
FINALDIR=`dirname $MANPDF`
echo PDF: $MANPDF
# Create the PDF if it's not in the cache dir or if the cached version is obsolete.
CREATEPDF=0
if [ ! -e $MANPDF ]; then
	echo Generating man page...
	CREATEPDF=1
else
	if [ $MANFILE -nt $MANPDF ]; then
		echo Man page newer than PDF, regenerating...
		CREATEPDF=1
	fi
fi

if [ $CREATEPDF -eq 1 ]; then
	mkdir -p $FINALDIR
	$MAN_CMD $MANSECTARG -t $MANARG | $PS2PDF_CMD $MANPDF
else
	echo Reading man page from cache...
fi
# Now open the PDF.
$OPEN_CMD $MANPDF

Jon Wight posted a script that gives you a command-line tool for opening man pages in Xcode's documentation viewer. There are lots of man-page viewers for Mac OS X but most work as Mac applications, leaving the command line behind. That's fine for some but not for longtime Unix geeks like me who spend a lot more quality time with Terminal.app than is probably healthy on a Mac.

So I thought I'd add my contribution, a script I wrote a while ago that renders man pages as PDFs and then opens them in Preview (or whatever your default PDF viewer is). The script is called "manpdf" (original). Use it as you would "man"-- for example either "manpdf time", or with a section number as "manpdf 3 time" (if you try those with plain "man" you'll see why adding a section number is useful).

Since there's a certain amount of overhead in rendering a man page to PDF, this script caches the PDFs once they're created. Later calls with the same arguments should be nearly instantaneous, even for big man pages like gcc's. The default cache location is ~/Library/Caches/manpdf. If you don't care about caching you could set that to /private/tmp/, or if you use multiple accounts on your Mac you might set it to /Users/Shared/.

This could be modified to use HTML, but the default HTML rendering is awful and I'm not sure how to insert improvements into the flow.

Update: A newer version of this script can be found in a later post.

#!/bin/bash

# Convert man pages to PDF and open them in the default PDF viewer.
# PDFs are cached when created.
# By Tom Harrington, tph at atomicbird dot com, 16 March 2005

# Directory to save cached PDFs in 
# (if you don't want long-term caching, you could use /tmp/).
CACHEDIR=~/Library/Caches

# Command to read PS from stdin and write PDF to an output file.
PS2PDF_CMD="/usr/bin/pstopdf -i -o"
# Command to open the resulting PDF once it's created.
OPEN_CMD="/usr/bin/open"
# Path to "man", which is expected to take the -w, -S, and -t args.
MAN_CMD="/usr/bin/man"

CACHEDIR="$CACHEDIR/manpdf"
if [ ! -e $CACHEDIR ]; then
	mkdir -p $CACHEDIR
fi

if [ $# -eq 1 ]
then
	MANSECT=""
	MANARG=$1
elif [ $# -eq 2 ]
then
	MANSECT=$1
	MANARG=$2
else
	echo "Usage: " `basename $0` "[section] name"
	exit
fi

if [ "$MANSECT" != "" ]; then
	MANSECTARG="-S $MANSECT"
fi

# Look for the command's man page.
MANFILE=`$MAN_CMD $MANSECTARG -w $MANARG 2>/dev/null`
if [ -z $MANFILE ]; then
	echo No manual entry for $MANARG
	exit
fi
# OK, got the man page.  Now get the name for the corresponding
# PDF.  The goal here is to organize cached PDFs in CACHEDIR
# according to man-page section, similar to the way /usr/share/man
# is organized into "man1", "man3", etc.
echo file: $MANFILE
MANSECT=`echo "$MANFILE" | sed 's/.*\.\([0-9]\)/\1/'`
MANPDF=$CACHEDIR/pdf$MANSECT/$MANARG.$MANSECT.pdf
FINALDIR=`dirname $MANPDF`
echo PDF: $MANPDF
# Create the PDF if it's not in the cache dir.
if [ ! -e $MANPDF ]; then
	echo Generating man page...
	mkdir -p $FINALDIR
	$MAN_CMD $MANSECTARG -t $MANARG | $PS2PDF_CMD $MANPDF
else
	echo Reading man page from cache...
fi
# Now open the PDF.
$OPEN_CMD $MANPDF

Jon's script has the advantage that Xcode's viewer includes hyperlinks to cross-referenced man pages. That can be really handy. Mine however doesn't require Xcode, which can also be really nice if you aren't working with Xcode but still want something nicer than ASCII rendering of the man page.