Mac Geekery

You can use the groff tool to convert manual pages into PostScript, PDF, or HTML form for pretty viewing, printing, posting to a webpage, easy searching with Spotlight, or any other purpose, if you like. Manpages are stored in a simple mandoc format for which the groff formatting tool has an understanding (indeed, groff is used by man to display the page in the first place). groff also has an understanding of a wide variety of other formats to display things in, however man only uses the normal display format so only the few that look into such things would notice the fun to be had.

First, to get a manual page that looks like the version man brings up, you tell groff to use ASCII or UTF8 as the output form. To get groff to do it, however, you need to tell it the location of the actual mandoc file, which man gives you with the -w flag.

groff -mandoc `man -w dscl` -T ascii
groff -mandoc `man -w dscl` -T utf8

To get a PostScript version of a manual page, you have two choices. Either let man do it for you or ask groff directly. To get man to do it, just pass the -t flag.

man dscl -t > man.ps
groff -mandoc `man -w dscl` -t > man.ps

More fun, I think, is opening that right in Preview. The open command lets you do this with the -f option, which takes stdin, saves it to a temporary file, and then opens it. Using the -a flag, we’ll tell open to use the program of our choice.

man dscl -t | open -f -a Preview
groff -mandoc `man -w dscl` -t | open -f -a Preview

Preview comes up, converts the file from PS to PDF for us, and we can now scroll through it and do whatever we want. It’s still a temporary file that will get cleaned on reboot, so you could alias a command to make this happen for most any manpage you wanted to see instead of being stuck in Terminal reading in less.

We can do more, though. If you want to go straight to PDF then you can use pstopdf to do that. Just pass -i to tell it to use stdin and -o to tell it where to put the output. In the standard tradition of Apple command-line tools, you must have a space in-between flags for some stupid reason.

groff -mandoc `man -w dscl` -t | pstopdf -i -o man.pdf

If you’d like HTML, that can be accomplished as well as groff groks HTML, too.

groff -mandoc `man -w dscl` -T html > man.html

How to Make It Useful

That was fun, but how can this be useful? Well, there’s a few ideas for this one.

Spotlight

To be fair, there’s a manpage importer for Spotlight that does this as well, but it only indexes the files, it doesn’t open them. There’s some programs like ManOpen to view them, but, well, it looks ugly.

So, if you have some space hanging around, convert all of your manual pages to PDF in a common area so Spotlight can index them and you can open and read them in a GUI.

#!/bin/bash


	

		
First we get a list of directories that contain manual pages.
		
The environment variable MANPATH has this for us. However,
		
Mac OS X doesn’t set this by default, so we’ll set it if
		
if’s unset.
	

	
if [[ -z $MANPATH ]]

then
    MANPATH=/usr/share/man:/usr/local/share/man:/usr/X11R6/man

fi

	
for DIR in `echo $MANPATH | sed ‘y/:/ /’`

do
        echo Processing $DIR

	

		
Each of these directories has subdirectories for each section
		
like man1, man2, etc.  Descend.
	

        SECTIONS=`ls $DIR`
        for SECTION in $SECTIONS
        do

	

		
To prevent the same terms in different sections from colliding,
		
create a directory for each section for the output files.
	

                if [[ ! -d $SECTION ]]
                then
                        mkdir $SECTION 2>/dev/null
                fi

                FILES=`ls $DIR/$SECTION`
                for FILE in $FILES
                do

	

		
Do not convert files we’ve converted before.  This allows this
		
script to be run for maintenance after updates or installs as well.
	

                        if [[ -f $DIR/$SECTION/$FILE && ! -f $SECTION/$FILE.pdf ]]
                        then
                                echo Converting $FILE in $DIR
                                groff -mandoc $DIR/$SECTION/$FILE -t 2>/dev/null | pstopdf -i -o $SECTION/$FILE.pdf
                        fi
                done
        done
done

This will take a while to convert when run, and will use a large amount of disk space for the resulting files. However, once you’re done you can content-search your manual pages and open them in Preview when you’ve found them. Also, because it checks for the existence of the destination file, you can either interrupt the script and finish at a later time or you can re-run the script after installs or upgrades to get added files. It won’t check for updated files, but if you care that much just delete the old ones and start again.

Webpage

Using the previous script, you can change the command and extensions using the information provided above to produce HTML files instead of PDF files. As you go along, generate the index files for the directories with the information you have and then just push this out to a webpage and you’ve got a nice documentation center.

#!/bin/bash


	
echo “
“ > index.html


	

		
First we get a list of directories that contain manual pages.
		
The environment variable MANPATH has this for us. However,
		
Mac OS X doesn’t set this by default, so we’ll set it if
		
if’s unset.
	

	
if [[ -z $MANPATH ]]

then
    MANPATH=/usr/share/man:/usr/local/share/man:/usr/X11R6/man

fi

	
for DIR in `echo $MANPATH | sed ‘y/:/ /’`

do
        echo Processing $DIR

	

		
Each of these directories has subdirectories for each section
		
like man1, man2, etc.  Descend.
	

        SECTIONS=`ls $DIR`
        for SECTION in $SECTIONS
        do

                if [[ ! -d $SECTION ]]
                then
                        # Every time we make a directory,
                        # update the main index file to
                        # link to it.
                        mkdir $SECTION 2>/dev/null
                        echo “
$SECTION
“ >> index.html
                fi

                if [[ ! -f $SECTION/index.html ]]
                then
                        echo “
“ > $SECTION/index.html
                fi

                FILES=`ls $DIR/$SECTION`
                for FILE in $FILES
                do
                        if [[ -f $DIR/$SECTION/$FILE && ! -f $SECTION/$FILE.html ]]
                        then
                                echo Converting $FILE in $DIR
                                groff -mandoc $DIR/$SECTION/$FILE -T html > $SECTION/$FILE.html 2>/dev/null
                                echo “
$FILE
“ >> $SECTION/index.html
                        fi
                done
        done
done

	
echo “
“ >> man1/index.html

echo “
“ >> man2/index.html

echo “” >> man3/index.html

echo “” >> man4/index.html

echo “” >> man5/index.html

echo “” >> man6/index.html

echo “” >> man7/index.html

echo “” >> man8/index.html

echo “” >> man9/index.html

echo “” >> index.html

A nice side-effect of this is that the files are smaller than PDF and Spotlight will index them as well. It’s just that they’re nowhere near as nice as the PDF versions when it comes to printing them.

Quick-View in Preview

The following shell function (bash) can be used instead of man to get a manpage in Preview instead. Add this to your .profile or something.

pdfman() { man $1 -t | open -f -a Preview; };

Now pdfman dscl will open in Preview.

Pretty Printing

Sometimes you know you just want to print the manual page. You could use pdfman above and then print, but why bother when the command line can do it for you?

printman () { man $1 -t | lpr; };

Now printman dscl will send a pretty PostScript version of the manual page to your default printer.

Select ratingCancel ratingPoorOkayGoodGreatAwesome