Man overboard

This post was going to be a simple discussion of a couple of ways to view Unix man pages on the Macintosh, but it quickly got out of hand as I started thinking of other ways to do it. It’s still certainly not complete, but I’ve had enough.

Manual pages--man pages for short--go back to the earliest days of Unix. The guys at Bell Labs knew that writing good software wasn’t enough; the documentation had to be complete, understandable, and at hand. This was back in the days of text-only terminals, when every command was typed and flexibility came not from ticking checkboxes in a window, but from adding dash options (like -a) to the command line string. Thus were born man pages, concise descriptions of the Unix commands and and their options, available at any time by typing man <name> at the command line.

Despite a quarter century of directing computers via mouse clicks, the command line has not disappeared because it’s often the easiest way to get many things done in a short period of time. If you intend to do much work in the Terminal or write shell scripts, you’ll be reading man pages.

The easiest way to view a man page on the Mac is the traditional Unix way: open a Terminal window and type something like man chmod at the prompt.

The first “screenful” of the man page will appear, filling the Terminal window. You can scroll through the rest of the man page, but you won’t be using the scroll bars. You’ll have to keystrokes like we did back in the days of glass TTYs. f will move you forward a screenful at a time, b will move you back. When you’re done and want to go back to giving commands instead of studying them, quit the viewer by typing q.

[Strictly speaking, these commands aren’t part of man; they’re part of a “pager” program called less. man formats the page and then sends (“pipes” in Unix-speak) the formatted page to less, which presents it one screen at a time and provides the scrolling controls.]

The advantages of using the traditional Unix way of viewing man pages are:

• It’s the fastest. All the other ways (but one) start by doing the equivalent of a man command and then do something else afterwards.
• It’s built-in. There’s nothing new to download and nothing to keep up to date.
• It always works. This is the corollary to the previous advantage; you can’t be missing a component, and you don’t have to worry about whether a new command is in your $PATH. The disadvantages of viewing man pages this way are: • The man page opens in and takes over the Terminal window you’re working in. Usually, you’d like to refer to the man page in one window while you construct your command in another. With the traditional method, you need to think ahead and open a second Terminal window just for viewing man pages. • There’s no GUI. As I said before, scrolling is done via the keyboard, not by flicking your mouse at a scrollbar. More important, although man pages often refer to other man pages, there is no hyperlinking; to go to another page you have to quit the one you’re in and issue a new man command. Not the sort of thing we expect in a browser-dominated world. AquaLess AquaLess is a system comprising a regular Mac application (called AquaLess) and a command-line tool (called aless) that gets installed in /usr/bin the first time you run the regular application. The aless command is meant to be used in place of the usual less command for paging lengthy output in the Terminal. Piping the output of a command through aless launches AquaLess and sends the output to it. AquaLess, being a normal Mac application, doesn’t force you to remember keyboard commands to scroll back and forth. More important for our purposes here, you can set aless to be your standard pager by putting the line export MANPAGER=aless  in your .bashrc (or .bash_profile or .profile) file. From that point on, man pages will be directed to AquaLess instead of the Terminal. The advantages of using AquaLess are: • You get a Mac-standard scrollable GUI • The man page automatically opens in a separate window, so you can continue to work at the Terminal. • You get Mac-standard Find (⌘F) and Find Next (⌘G) commands for searching through the man page. • AquaLess can be configured through a normal Preferences window to use any monospaced font and font size. The disadvantages of using AquaLess are: • There are no links to other pages, just plain text with the command names. • There’s no obvious way to change the initial window width, so if you use a large font (as I do), the window starts out too narrow to display the full width of the man page. Since AquaLess is an open source project, you can probably dig into the source code to change this, but I haven’t done so. Dedicated programs ManOpen, Man Handler, and Man Viewer are all standalone Mac applications that let you view man pages. They’re remarkably similar in look and fairly similar in behavior, so I’m considering them in one lump. The advantages of the dedicated viewers are: • They open man pages in a separate window. • All have Mac-standard Find and Find Next commands. • ManOpen has clickable links to other man pages. • ManOpen comes with a command-line tool, openman, that lets you launch it from the Terminal. The disadvantages of the dedicated viewers are: • They all use a small, ugly font (10-point Monaco, I think) that can’t be easily changed. • Man Handler and Man Viewer don’t have clickable links to other man pages. • ManOpen’s Preferences setter is apparently supposed to have three sections--General, Appearance, and Man Page Viewer--but only one section shows for me. • Man Viewer takes forever (a couple of minutes on my iBook G4) to load because it loads all the pages into some cache. • Man Viewer is clumsy to use because you have to select the page from a list instead of just typing the command name and hitting the Return key. Bwana Bwana uses your browser to display man pages. When you install it, Bwana does two things: 1. It tells your Mac that it should be the handler for the man: URI scheme. 2. It sets up some communication with your browser so that when you type, say, man:chmod into the browser’s address field of your browser, up will pop the chmod man page. Because Bwana is the man: URI handler, it works with the Macintosh’s built-in open command. I’ve written a one-liner shell script called bman that uses this property. #!/bin/bash open man:${1}


Now I can type bman chmod in the Terminal and the chmod man page will appear in my browser.

The advantages of using Bwana are:

• It opens the man page in a separate window.
• It uses whatever monospace font you prefer in your browser.
• It creates clickable hyperlinks to other man pages referred to in the text.

The only real disadvantage of using Bwana is that it’s a bit ugly out of the box because of two curious decisions:

1. It retains the terminal convention of using underlines instead of italics for emphasis.
2. It replaces characters that would be bold in the terminal with standard weight characters colored red.

Because Bruji makes the source code for Bwana available, I’ve altered and recompiled my copy to use italics for emphasis and a black bold font instead of medium red. My changes are available on GitHub, or you can just download the compiled app.

PDF solutions

The man command is built on the old Unix troff/nroff markup system and has long had the ability to create well-formatted PostScript versions of man pages that use proportional fonts and are ready to print. To turn this behavior on, you use the -t--for “typeset,” presumably--option.

This MacWorld article shows how you can set up a command that uses a combination of man -t and Preview’s ability to open PostScript files to read your man pages in a nicely typeset format. Even better is this shell script, which converts the PostScript to PDF and then saves a copy of the page on your hard disk for quicker retrieval later.

The advantages of converting the man pages to PDF are:

• The pages open in a separate window.
• It uses proportional fonts, which are easier to read.
• You can immediately print a man page from Preview if you think it would be helpful to you.

The disadvantages of converting to PDF are:

• There are no clickable hyperlinks to other pages.
• Preview may not open to the size and magnification you like.

Direct HTML output

Groff (the GNU version of troff/nroff) extends the traditional Unix formatting tools by providing an option for HTML output in addition to plain text and PostScript. I’ve written a experimental man page viewer, hman, that takes advantage of this extension:

1:  #!/bin/bash
2:
3:  f=man -w $1 4: groff -mandoc -Thtml$f > ~/Desktop/$1.html 5: open ~/Desktop/$1.html


Line 3 gets the location of the markup source file of the page. Line 4 generates the HTML via groff, and Line 5 opens the page in the default browser.

I said earlier that this was experimental. If I were going to use this on a regular basis, I’d add the ability to:

• Expand source files that are stored in compressed form.
• Store the generated HTML files on disk for quick retrieval later.
• Turn references to other pages into links.

None of these would be especially difficult, but I haven’t done them because I’m generally not happy with the HTML produced by groff. In testing this script on several man pages, I’ve found that groff often creates bizarre spacing that makes the pages hard to read.

Compare that to the much nicer layout from Bwana.

HTML output via server

There’s program called manServer that takes a different approach from the other solutions presented here. Instead of using t/n/groff to format the page, it reads the markup directly and does its own formatting.

manServer is probably best run as a standalone server (with the -s option), delivering pages to your browser via port 8888. It would be easy enough to have manServer -s run as a Login Item (the way LaunchBar and Quicksilver are run) and to create a shell script

#!/bin/bash

open http://localhost:8888/\${1}


that will open pages from the Terminal.

The advantages of using manServer are:

• The man pages open in a separate window.
• It creates clickable hyperlinks to other pages.
• The pages are nicely formatted with proportional font.

The disadvantages of using manServer are:

• When there is more than one man page associated with a particular name--for example chmod is both a command-line program and a system call (a C function)--manServer stops and asks you which one you want. The standard man command, and all the other variants discussed in this post, display the command (which is usually what you want) and give you the option to display the system call1.
• In my experience, some man pages don’t get displayed. For example, I can’t get manServer to show the man page for the chmod system call.
• It has a tendency to add a space character at the beginning of its links, which makes those links unusable. This is especially prevalent at the end of the groff man page, where most of its links to are contaminated by leading spaces.

Text editor

Finally, there’s a way to have man pages appear in your regular text editor, if that text editor has a command-line launcher (as TextMate and BBEdit do). As with AquaLess, add a line like one of these to your .bashrc file:

export MANPAGER=mate    # for TextMate


or

export MANPAGER=bbedit  # for BBEdit


Now man will send the formatted output to your text editor instead of less. Unfortunately, a standard formatted man page includes many control characters and doubled letters that will look like garbage in your editor. But we can change the standard formatting.

Make a copy of /etc/man.conf and put it in your home directory. Open the copy and scroll down to the line that looks like this2:

NROFF   /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c


Change it to look like this:

NROFF   /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c -P-b -P-u


Those last two options will stop groff from bolding and underlining characters in the formatted output. Now you can have man use this configuration file instead of the default by using the -C option:

man -C ~/man.conf chmod


You can, of course create a shell script or an alias that always uses the -C option.

• If you’re a programmer, your editor is probably the application in which you’re most comfortable.
• You can do complex searches using regular expressions.

• There’s no formatting at all (unless you have TextMate’s Man Pages Bundle, which I don’t like the look of).
• There are no clickable hyperlinks to other man pages. While it would be relatively easy to add a command to display the man page for the currently selected word, this would require two steps to jump to a new page rather than the single step needed with true hyperlinks.

Conclusions

I’m using my customized version of Bwana, because it gives me the best balance of appearance and usability. It’s only downside is its use of monospace fonts, and since I spend much of my day looking at monospace fonts in my text editor, that’s not such a big deal.

You may find the tradeoffs lead you to a different conclusion. Everyone has different tastes and different work habits. I encourage you to try out two or three solutions to see what works best for you.

Update 3/27/09
Fixed links to Man Handler and Man Viewer. Man Open => ManOpen.

1. Different types of man pages are separated into numbered sections, and when the same name appears in two different sections, the man command displays the one in the lower-numbered section. Command-line programs are in Section 1, so they always take precedence over system calls, configuration files, etc.

2. The man.conf file also has a line for setting the PAGER, which does the same thing as the export MANPAGER environment variable setting.