Next post Previous post

Man overboard

March 27, 2009 at 1:00 AM by Dr. Drang

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.

Traditional

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:

The disadvantages of viewing man pages this way are:

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:

The disadvantages of using AquaLess are:

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:

The disadvantages of the dedicated viewers are:

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:

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 disadvantages of converting to PDF are:

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:

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 disadvantages of using manServer are:

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.

The advantages of reading man pages in your text editor are:

The disadvantages of using your text editor are:

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.

Tags:

  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. ↩

Next post Previous post