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.

Ryan Irelan has produced a series of shell trick videos based on BrettTerpstra.com posts. Readers can get 10% off using the coupon code TERPSTRA.

Brett Terpstra

Brett is a writer and developer living in Minnesota, USA. You can follow him as ttscoff on Twitter, GitHub, and Mastodon. Keep up with this blog by subscribing in your favorite news reader.

This content is supported by readers like you.