Linking to Apple’s online man pages
December 24, 2016 at 5:26 PM by Dr. Drang
Earlier this afternoon, John Gruber tweeted out a scripting tip:
AppleScript tip:
# This takes ~5 secs:
get computer name of (system info)
# Instant:
do shell script “scutil —get ComputerName”
— John Gruber (@gruber) Dec 24 2016 1:54 PM
I wasn’t surprised to see that a shell command is much faster than the equivalent AppleScript, but I was surprised to see a command I’ve never used before. And as I was looking up the uses of scutil, I realized I needed to improve my system for linking to Apple man pages.
As I mentioned back in May, over the years Apple has changed where it keeps its online man pages, messing up old links all over the internet. I was later told Apple was going to fix that with redirects, but in my experience older links still get you this:
To make it easy to link to the current man pages, I wrote this simple little Keyboard Maestro macro (which could just as easily be a TextExpander snippet):
The text in the Action is
https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man1/%|%.1.html
where the %|% part tells Keyboard Maestro to put the cursor in that spot so I can type the name of the command.
I’ve been using this command for months and have always meant to share it but kept forgetting. Ironically, scutil is a particularly poor command to use as an example of the macro’s value, because the macro assumes the man page is in Section 1, while scutil is in Section 8.
What are the sections? They separate the commands by usage and were, I think, meant to makes searches go faster back when computers were much slower. MacOS gets its section divisions from BSD:
| Section | Description |
|---|---|
| 1 | General commands |
| 2 | System calls |
| 3 | Library functions, covering in particular the C standard library |
| 4 | Special files (usually devices, those found in /dev) and drivers |
| 5 | File formats and conventions |
| 6 | Games and screensavers |
| 7 | Miscellanea |
| 8 | System administration commands and daemons |
Although most of the commands I look up are in Section 1, I’ve never been completely happy with this macro because it doesn’t always work. The section problem with scutil got me thinking about ways to improve the macro.
Update 12/25/2016 7:04 AM
Once again, I started off by taking the easy way out and then decided to fix it. There are, in fact, many man page sections that aren’t simply numbered. There’s Section 1m, for example, which covers commands built from DTrace, like iotop. The URL for its man page is
https://developer.apple.com/…/man1/iotop.1m.html
You can see how these multicharacter sections are handled: the first character is used in the manx part before command name, and the whole section name is used in the suffix immediately after the section name.
This morning, before the rest of the family got up to open presents, I decided it would be easy to extend the macro to handle these multicharacter section names. These sections typically cover more obscure commands that I’m unlikely to link to, but it wasn’t that hard to change the macro to handle them, too.
Beyond this point, the post has been edited to reflect the further improved macro. Merry Christmas!
As best I can tell, there’s no way to tell the man command to return just the section name of a man page, so I decided to extract it from the man page itself. The section name is given in parentheses in the header of the man page. For example:
SCUTIL(8) BSD System Manager's Manual SCUTIL(8)
The header is usually the second line (after a blank line), but sometimes it’s first. So what I needed was a pipeline to
- get the man page;
- delete any blank lines at the top; and
- return just the section name from the header.
After a few tries, I came up with this:
man scutil | sed -E '/^$/d' | sed -nE '1s/^[^(]+\(([^)]+)\).+$/\1/p'
The man page is piped to the first sed command, which deletes all the blank lines. Deleting all the blank lines is overkill, but it was an easy command to write. The result is then piped to the second sed command, which pulls out the first parenthesized string it encounters and prints out just that. I always use the -E option for sed because it provides “extended” regular expressions, instead of the ridiculous “basic” regular expressions that require backslashes in front of almost everything.
With that worked out, the improved Keyboard Maestro macro looks like this:
The brief pause at the top allows the deletion of the four-character trigger to occur even on my old 2010 MacBook Air. Then the user is prompted for the name of the command to look up:
With the name of the command in hand, the macro runs the pipeline shown above (using the name of the command just entered rather than scutil) to get the section name. It then gets the first character of the section name, because we’ll need that to build the URL. Finally, it constructs the URL out of all these pieces and pastes it wherever you have the cursor. The macro works in a browser URL field as well as in a text document.
So thanks to John Gruber for showing me scutil and reminding me that I needed to fix my man page link macro.
