Manning up: TextMate Meets Man Pages

Published on Friday, March 14, 2008 in command line and textmate

Navigating through man pages in a terminal window doesn't exactly rank as a highlight of this developer's day. The experience feels like 1971 for a reason, and that means of interaction just leaves something to be desired. Perhaps you could make the argument that A) people that read man pages don't rank humane interfaces as a top priority, or that B) I could spend more time mastering the ways to navigate via less (the default man page browser in OS X). But, believe it or not, apparently I'm not alone in my crazy desire to consult man pages outside of the terminal. So with web-based solutions, PDF generators, and full-blown apps dedicated solely to "manning up," where should we turn? Queue The Pragmatic Programmer for some welcome words of wisdom:

Use a Single Editor Well

The editor should be an extension of your hand; make sure your editor is configurable, extensible, and programmable.

For me, that editor is undoubtedly TextMate. I already spend most of my day in TextMate, be it for coding, blogging, editing wiki pages (and other Safari-based content), or sometimes even writing e-mail. So, if I can use TextMate to find my way around a man page, that's an all-around win.

Goal

While working in the terminal, be able to quickly open a man page in TextMate.

Making it happen

First, install the mate shell command. (Even if you have no interest in viewing man pages in TextMate, this command is simply indispensable for anyone that even occasionally ventures into the land of the terminal.)

Now that we have access to TextMate from the command line, we can assemble a quick script to get us the rest of the way toward achieving our goal. I keep all of my custom scripts in a .scripts directory that I include in my path, so I'll define this handy scriptbaby in a file named mman (for "mate man") in that directory.

$ ls -l /Users/jason/.scripts/mman 
-rwxr-xr-x@ 1 jason  jason  43 Mar 14 15:52 /Users/jason/.scripts/mman

And once we drop a bit of Unix-fu into that file, we'll be good to go.

#!/usr/bin/env bash

man $1 | col -b | mate

To see it in action, just use mman anywhere you would have previously used the vanilla man command.

Running mman in Terminal to open man page in TextMate

Kicking it up a notch?

That approach has served me well for several months now, but in the course of writing this post, I came across an associated TextMate bundle that some folks may find helpful as well. The TextMate Man Pages bundle offers some (minor) syntax highlighting, the ability to open a man page from within TextMate, and the ability to use Command + Shift + T (i.e., "Go To Symbol") to quickly find and access key sections of the man page by name.

Showing off the TextMate man page bundle

Now go forth and devour some man pages already.