Next post Previous post

Last man standing

March 26, 2022 at 6:57 PM by Dr. Drang

Back in 2009, I wrote a post about various (mostly unsatisfying) ways of viewing manual (man) pages on the Mac. Many of the commands and apps in that post are either dead or abandoned, and some years ago I returned to a system that’s not much different from what I used when I was running Linux back in the early 2000s. I recently expanded my script to handle sections the same way the man command does.

At its most basic, the man command is invoked like this:

man [section] command

where command is the name of the command you want to learn about. Man pages are categorized in sections, and you can add the optional [section] if necessary to eliminate ambiguity.

For instance, there are two man page entries for printf. One, in Section 1, covers the printf user command, which you can run interactively from the Terminal or put in shell scripts. The other, in Section 3, covers the printf function from the Standard C library.

The main problem with the man command is that it takes over your terminal window—you can’t refer to it while you’re constructing a command unless you open a second terminal window first or use the control-click trick. To get around this problem, I wrote a short shell script, called bman, that opens the man page in a new BBEdit window. Since I always have BBEdit running, this works just about as fast as the regular old man command.

I invoke it this way from the command line,

bman [section] command

using the same basic structure as man itself. For example, bman col will pop up this window:

Man page for col in BBEdit

If the man page is long, I can use all the familiar BBEdit search commands I use every day to find what I want.

Here’s the code for bman:

bash:
 1:  #!/bin/bash
 2:  
 3:  # Interpret the arguments as command name and section. As with `man`,
 4:  # the section is optional and comes first if present.
 5:  if [[ $# -lt 2 ]]; then
 6:    cmd=${1}
 7:    sec=''
 8:  else
 9:    cmd=${2}
10:    sec=${1}
11:  fi
12:  
13:  # Get the formatted man page, filter out backspaces and convert tabs
14:  # to spaces, and open the text in a new BBEdit document.
15:  man $sec $cmd | col -bx | bbedit
16:  
17:  # Set the document name and cursor position within BBEdit
18:  osascript <<OSAEND
19:  tell application "BBEdit"
20:    set name of front document to "$cmd"
21:    select insertion point before character 1 of front document
22:  end tell
23:  OSAEND

I think I’ve put enough comments in to explain what’s going on. What may be unfamiliar to you is the col command in the pipeline on Line 15. The man command outputs a lot of weird control characters to create bold and underlined words, and the purpose of col -b is to filter those out. Also, the -x option turns tabs into spaces, which I’ve found helpful in keeping the text aligned the way it should be.

Apple used to have all of the OS X man pages online.1 Accessing them from a web browser was certainly slower than getting them locally, but the online versions were nicely formatted with proportional fonts. Unfortunately, during one of Apple’s many fits of automation hatred, the online man pages were either deleted or moved to such a secure and undisclosed location that even Google can’t find them anymore.

If you use a text editor other than BBEdit, you can probably adjust the bman script to fit your needs. The lines that handle the arguments should stay the same, as should the Line 15 up to the last term in the pipeline. You’ll have to change the bbedit to whatever command invokes your editor. As for the AppleScript in Lines 18–23, you’re on your own.2

Update 3/27/2022 8:28 AM
Via Twitter, mikeymikey told me about the x-man-page:// URL scheme, which I had somehow never heard of before. But like the control-click trick, it brings up a new Terminal window with the man page, I came to the conclusion some time ago that I preferred to have my man pages displayed in BBEdit.

This morning’s email brought me messages from Christopher Waterman and Olav Brinkmann, both of whom told me that I could not only set the BBEdit window title directly from the bbedit command (which I had mentioned in the final footnote), but that there was also a way to scroll to the top. With Line 15 changed to

man $sec $cmd | col -bx | bbedit --view-top --clean -t $cmd

I can eliminate all the AppleScript that comes after.

Olav suggested the --clean option. It sets the state of the new document to “unmodified,” which means you can close the document without needing to confirm you don’t want to save it. Christopher suggested adding -m "unix-man-page", which sets the language for syntax coloring, but I haven’t found that it changes the way the page looks. I’ll look into it.

(Side note within a side note: Shouldn’t I be putting the variables in quotes? Yeah, that’s generally a good habit to get into, but sections and command names never have spaces in them, so I think I’m safe here. If you want to adopt this script and feel nervous about the lack of quotes, by all means add them.)

Christopher and Olav are so nice that neither of them pointed out the irony in my writing a post about viewing man pages while missing options that are clearly in the bbedit man page.

  1. That I’m calling them “OS X man pages” should tell you how long ago this was. ↩

  2. Many of you will know that I could have set the new document’s title by adding a -t option to the bbedit command on Line 15. I didn’t know that when I first wrote bman, and since I need AppleScript to put the cursor at the top of the document anyway, I’ve kept the title change in the AppleScript section. ↩

Next post Previous post