50.9 Reading a Permuted Index

The first time that people new to UNIX take a look at the front of the system's UNIX Reference Manual, they are likely to be surprised by the most unlikely looking document: the ubiquitous permuted index. The index looks something like the one shown below, which actually shows a complete permuted index based on the three commands ar, at, and awk. This miniature index is used as an example throughout this article.

                          maintainer   ar: archive and library ........... ar(1)
                                 ar:   archive and library maintainer .... ar(1)
                                time   at: execute commands at a later ... at(1)
                 processing language   awk: pattern scanning and ......... awk(1)
                         at: execute   commands at a later time .......... at(1)
                                 at:   execute commands at a later time .. at(1)
awk: pattern scanning and processing   language .......................... awk(1)
           at: execute commands at a   later time ........................ at(1)
                     ar: archive and   library maintainer ................ ar(1)
             ar: archive and library   maintainer ........................ ar(1)
                       language awk:   pattern scanning and processing ... awk(1)
           awk: pattern scanning and   processing language ............... awk(1)
                        awk: pattern   scanning and processing language .. awk(1)
     at: execute commands at a later   time .............................. at(1)

Like the UNIX Reference Manual itself, the permuted index takes a little getting used to, but it is fairly useful once that hurdle has been crossed. To find the command you want, simply scan down the middle of the page, looking for a keyword of interest on the right side of the blank gutter. When you find the keyword you want, you can read (with contortions) the brief description of the command that makes up the entry. If things still look promising, you can look all the way over to the right for the name of the relevant command page.

The key to the UNIX Reference Manual is the fact that each command is treated on a separate page - there are no continuous page numbers. This makes it easy to add new pages whenever a new command is added to the system. At the same time, if you know the name of a command, information about it is always easy to find because pages are ordered alphabetically, just like they are in a dictionary.

But what if you don't know which command to look for in the first place? If you are at a terminal on a Berkeley UNIX system, you can use the apropos (50.2) command, like this:

% apropos scanning
awk(1) - pattern scanning and processing language

But if you're using another UNIX variant or you are not at a terminal, the permuted index is your best bet.