Info man

This is not a post about a superhero librarian.

Last week, as I was trying to figure out what the -s option to the sort command really means, I ran into a problem that drove me crazy during my Linux years but which I thought I’d left behind when I switched back to the Mac. Here’s the bottom of the sort man page:

The full documentation for sort is maintained as a Texinfo manual. If the info and sort programs are properly installed at your site, the command

    info sort

should give you access to the complete manual.

Unlike man pages, a simple but tremendously useful type of documentation initiated by the original Unix developers at Bell Labs, Texinfo manuals and the info reader are clumsy, hybrid abominations that manage to combine the worst of plain text and hypertext documentation. As is often the case in hypertext docs, the information is spread out over several “nodes” instead of all being in one compact file; but like plain text, there is no graphical user interface—navigation among the nodes is done though weird keyboard commands.1

Linux man pages were often extremely short stubs that said little beyond “go to the info page.” OS X man pages, thank goodness, aren’t that stripped down, but they have their own problem: they sometimes tell you to go to an info page that doesn’t exist.

That’s the case with sort. After reading that note at the end of the sort man page, I typed info sort into the Terminal and got… another view of the man page. Despite the note at the end of sort’s man page, Apple doesn’t include info files for sort in OS X.2

So what should you do if the man page doesn’t explain a command to your satisfaction and Apple didn’t include its info pages? Well, the one nice thing about the Texinfo format is that it can be converted to HTML, and some nice sysadmins have done the conversion and made the HTML available to all of us on their servers. Once such server is at NYU: here’s the top node of its info catalog. If you go there looking for the sort pages and can’t find them, don’t despair. They’re kept under the text utilities node, along with cat, uniq, head, and some other old friends.

  1. Weird if you’re not an Emacs user. During the year or two that I used Emacs regularly, the info system didn’t seem too bad, but that muscle memory left me long ago. 

  2. In fact, if you look in /usr/share/info, you’ll see that, apart from the Emacs help files, Apple doesn’t include many info pages at all. But if you’re looking for the full story on uucp, they’ve got you covered.