Next post Previous post

Return to the planet of man pages

January 1, 2025 at 9:48 PM by Dr. Drang

Inspired by Brett Terpstra’s post today about viewing man pages in iTerm via the x-man-page handler, I made some changes to the way Terminal on my Mac displays man pages and have been thinking—again—about how I should link to man pages here on the blog.

Let’s start with Terminal. Terminal has a profile for displaying man pages that you can, and should, adjust via its Settings. I say you should adjust it because the default background color is a disgusting yellow that no one should be forced to look at. Also, the font size is too small. Here are some of the changes I made,

Terminal settings for man pages

and here’s how the man page for tr looks with those settings,

Terminal window with man page of tr

Because I use the bash shell instead of fish, I wasn’t sure what I’d have to do to get Brett’s xman function to work for me. Turns out, all I had to do was suppress any shame I might feel for direct theft. Now I have this line in my .bashrc file,

function xman() { open x-man-page://$@ ; }

which is exactly what you’ll find in Brett’s post. With this, typing

xman tr

will bring up a new Terminal window that looks like that last screenshot.

But will I use this? Probably not. I’m still happy with my bbman command, which brings up the given man page in a new BBEdit window:

BBEdit window with man page of tr

It’s obviously plainer than the Terminal version, but as explained in my bbman post, I have a Man Page AppleScript that allows me to select the name of a command in any BBEdit window (including one that’s showing a man page) and bring up that command’s man page with a simple ⇧⌘M keystroke.

So why mess around with Terminal’s man page profile and add xman to my .bashrc? It goes back to a problem I’ve had for several years: the best way to link to a man page here on ANIAT.

In the old days, Apple liked to show off OS X’s Unix heritage and had a full set of man pages available on apple.com, and that’s what I would link to when writing about a command. Apple moved those pages once or twice and eventually got rid of them entirely. So I started linking to either GNU/Linux versions of the man pages—which often have different sets of options—or the OS X/macOS versions on SS64.com—which tend to be out of date and not what you’d see if you opened a local man page.

Recently, I’ve been saving the plain text man pages I get from bbman to the Leancrew server and linking to them there. For example, in yesterday’s post, I linked to the tr command. If you click on that link, you’ll be taken to

https://leancrew.com/all-this/macman/tr.1.txt

which is the text of the current tr man page on Sequoia.

You see where this is going, right? I’m considering doing links like this: tr command, which will open

x-man-page://tr

If you’re on a Mac, clicking that link will bring up a dialog asking to open the man page in Terminal (unless you’re Brett, in which case it will ask about iTerm); if you allow it, the man page will open locally.

This has some advantages:

There is one serious, perhaps fatal, disadvantage: It works only if you’re reading the blog on a Mac. I think I could work around this by using JavaScript to send Macs an x-man-page link and other platforms a text file link. This would, of course, entirely wipe out the third advantage above. But I’d live with that if I thought it would improve the blog.

What do you think? If enough readers want links to local man pages via x-man-page, I’ll try to set it up. If not, I’ll stick with sending you to text files.1

Update 2 Jan 2025 11:10 PM
Jeff Johnson, maker of StopTheMadness, sent a Mastodon toot with an improved version of the xman function that allows the user to specify the section number before the command name. This makes xman more like man, so you can call

xman 3 printf

to get the man page for the library function, and

xman 1 printf

or just

xman printf

to get the man page for the command.

Because I can’t leave well enough alone, I made a slight change to Jeff’s code. Here’s mine:

function xman() {
    if [[ "$#" -lt 2 ]]; then
        open x-man-page://"$1"
    else
        open x-man-page://"$1"/"$2"
    fi
}

Looking at Brett’s page, I see he’s updated his xman to make it more fish-like, and he’s also changed the name to nman. (Or did he always call it nman?. It’s hell getting old.)

  1. Or maybe to HTML files if I can figure out how to make the output of man2html look decent. The default output looks awful. ↩

Next post Previous post