Man page followup
April 13, 2014 at 11:44 PM by Dr. Drang
When I checked my RSS subscriptions this morning, I found two followups to my recent man page post, one by Nathan Grigg and one by Rob Wells. These came after several tweets and emails on the topic. Everyone has their own favorite way to get at man pages. I don’t think any of the suggestions I was given will become my favorite way, but I thought it worth mentioning some of them. You never know what will click with you.
To recap, here’s the problem everyone wants to solve:
You’re in the middle of typing a command at the Terminal, and you realize you need to look up an option or some other aspect of the command in its man page. You can’t issue the man command without deleting what you’ve already typed, which might be extensive if you’re putting together a long pipeline. What’ll you do? What will you do?1
Nathan’s trick is specific to the zsh shell, but there’s a similiar—albeit slightly slower—technique available to bash users. In a nutshell, Nathan saves the half-written command into a sort of buffer or command stack that zsh has, opens the man page, then pulls the half-written command back after finding what he needed. As Nathan points out, the most useful thing about this technique is
… it is useful beyond just looking at manuals. Often while typing some command, I realize I need a quick mkdir or cd or even ls before I’m ready to execute.
Personally, I wouldn’t use this for reading man pages because I like having the man page in a separate window, but I’ve often found myself constructing a long command only to realize I’m in the wrong directory and have to stop to cd to the right place.
As it happens, there’s a set of keystrokes you can use in any shell that do what Nathan does almost as efficiently. They’re part of the Emacs keybindings that Mac programs have enabled by default.2 Control-U deletes everything on the command line from the cursor back to the beginning, putting it in a special “kill ring,” which is like the Mac’s Clipboard, but separate from it. You can then type cd or whatever command you need, and when that command is finished, bring back (“yank”) the half-written one from the kill ring with Control-Y.
Several people mentioned the Control-U, Control-Y trick. I’d never thought of it for man pages because, as I say, I prefer reading them in a separate window as I look at the command I’m constructing. But it’s a great trick to know when you realize you need to run a command before the one you’re in the middle of building.
Rob’s post describes a couple of techniques for bringing up man pages. First, there’s a LaunchBar search template that uses OS X’s built-in x-man-page:// URL scheme.3
Invoking this from LaunchBar will bring up the same Terminal window that appears when you use the Control-click method I described. Several people told me about ways they used x-man-page://. It, like open, pbcopy, and pbpaste, is a holdover from the days when Apple appreciated the Unix users among its customer base and provided nice tools for them. Memories…
Rob also mentioned Dash, the multi-language documentation browser from Bogdan Popescu. As I said in a Twitter conversation with Ryan Lane, who also recommended it, I’ve tried Dash but it’s never stuck with me. I should probably give it another look.
I appreciate all the suggestions, including those I didn’t mention here. One thing I noticed about all of them is that they’re very keyboard-centric. I suspect the suggesters were all slightly appalled by the notion of using the mouse or trackpad to bring up a man page. I’m sympathetic to the notion that keyboarding is faster—I’ve certainly created my share of keyboard shortcuts—but I’m not convinced keyboarding is faster in this case. And I’m always cognizant of this bit of wisdom from Bruce Tognazzini:
We’ve done a cool $50 million of R & D on the Apple Human Interface. We discovered, among other things, two pertinent facts:
- Test subjects consistently report that keyboarding is faster than mousing.
- The stopwatch consistently proves mousing is faster than keyboarding.
This contradiction between user-experience and reality apparently forms the basis for many user/developers’ belief that the keyboard is faster.
People new to the mouse find the process of acquiring it every time they want to do anything other than type to be incredibly time-wasting. And therein lies the very advantage of the mouse: it is boring to find it because the two-second search does not require high-level cognitive engagement.
It takes two seconds to decide upon which special-function key to press. Deciding among abstract symbols is a high-level cognitive function. Not only is this decision not boring, the user actually experiences amnesia! Real amnesia! The time-slice spent making the decision simply ceases to exist.
While the keyboard users in this case feels as though they have gained two seconds over the mouse users, the opposite is really the case. Because while the keyboard users have been engaged in a process so fascinating that they have experienced amnesia, the mouse users have been so disengaged that they have been able to continue thinking about the task they are trying to accomplish. They have not had to set their task aside to think about or remember abstract symbols.
Keyboarding with LaunchBar to get to a file or application is certainly faster than using the mouse to dig around in folders. I suspect, however, that Control-clicking a word that’s on the very line you’re editing is faster than keyboarding. But maybe I think that because I’m a slow typist.
Update 4/14/14
Benny Kjær Nielsen (you know, the MailMate guy) tweeted me this morning about the adaptive man page command in Terminal’s menu. It’s named , where xxx is the command to the left of the cursor. It’s keyboard equivalent is given as ⌃⌘?, which really means ⌃⌘⇧/.
It’s a technique worth knowing, but I doubt I’ll use it much. Two reasons:
- The ⌃⌘⇧ combination feels very clumsy to me. I’m OK with the ⌃⌥⌘ three-key combo because they’re all in a row, but when the Shift key screws up the alignment and makes me have to look down at what I’m doing. I could, of course, change the default shortcut, but that leads to the second reason.
It’s kind of dumb about what it considers to be the command to the left of the cursor. If, for example, you type
sort -nand then type ⌃⌘⇧/, you’ll get a new Terminal window telling you that there’s no man page for the
ncommand. It’s smart enough to not include the hyphen, but somehow not smart enough to know that the hyphen means it isn’t a command.
Since I often find myself partway through a set of options when I realize I need to look something up, this second problem will make the shortcut more a source of confusion than a help. It may work well for you, but I’ll stick with Control-clicking.
