Shell Tricks: man pages

Man pages make Unix go ‘round. I can’t think of any system that’s better documented, and the answers are almost always right at your fingertips.

There are a dozen ways to view a man page, starting with man [command] on the command line, which is by far the most common and often the most useful. But with a few tricks, you can load your man pages into something that allows better search, screen-permanence, and easier copying for saving example lines, etc..

Preview.app

The first trick I’ll show you is how to get a man page open in Preview.app. It’s simple, the man command has an output format ready for PostScript conversion:

man -t [command] | open -f -a Preview

An aside about the open command… You can open any Mac app, or open files directly with the app, using open (OS X only). The -a flag tells open which app you want to open, and accepts a simple application name or a full path. Leaving that off and running it directly on a file or URL will use the default app for that type. The -f switch tells it to read input from STDIN. Also, the -F switch will open it “fresh,” meaning no windows are restored. That can be a handy one if you have an app crashing on a particular document that keeps restoring on launch. open -a "Marked 2" filename.md is a fast way to open a Markdown file in Marked 2.

To get a similar effect in other apps that output man-formatted pages, such as git help, you can spell out the equivalent like this:

MANWIDTH=80 MANPAGER='col -bx' git help rev-parse \
| groff -P-pa4 -Tps -mandoc -c | open -f -a Preview.app

the -P-pa4 sends an A4 page size to the groff printer, which is the only way I get output that doesn’t have split lines over page breaks.

In your text editor

You can use a similar trick to send your man pages to an editor like Sublime, which can take input on STDIN and create a temp file automatically. With the subl tool installed:

MANWIDTH=80 MANPAGER='col -bx' git help rev-parse | subl

This can be aliased in your .gitconfig as:

shelp = "!shelp() { MANWIDTH=80 MANPAGER='col -bx' git help \"$@\" | subl ;}; shelp"

Note that git help has another interesting shortcut that lets you jump to the web-based version of local documentation: git help -w [command].

Third party apps

There are quite a few handy third-party tools for viewing man pages as well. vimpager (available through brew) is an alternative to less that you can use in a man command with the -P flag: man -P vimpager groff. Depending on your Vim setup, this can give you syntax-highlighted, easy-to-navigate man pages. MANPAGER=vimpager man groff has the same effect, and you can export MANPAGER=vimpager in your profile to have it be the default.

Bwana is a tool for opening man pages in your web browser. Once installed, you can use open man:groff to open the groff man page in your default browser. You can also use it directly in the browser window by just typing “man:groff” as your url.

There’s a handy, dedicated man page viewer called ManOpen, too. It can run “apropos” searches and open any page from a text field, including easy linking between associated man pages. It has a url scheme: “x-man-page:groff” will open it from the command line or from a web browser. I use a bash function that runs open x-man-page:$1 when I type oman groff.

Last, but not at all least, is Dash. Dash can load all of your system man pages as a Docset, and then you can access it with the Dash url handler: open "dash://man:groff". All the benefits of Dash with the same accessibility as the other methods.