Searching Online Manual Pages (Unix Power Tools, 3rd Edition)

2.4. Searching Online Manual Pages

When the other techniques in this chapter don't find the information you want, you can try searching the online manual page (Section 2.1) files. You'll probably have to wade through a lot of stuff that you don't want to see, but this method can work when nothing else does. As an example, you remember that there's some command for chopping columns out of a file. You try man -k or apropos, but it only mentions colrm and pr, and those aren't what you want. You'll usually be able to narrow your search to one or two manual page sections (Section 2.1); here, you know that user commands are in section 1. So you go to the manual pages and do a case-insensitive search through all the files for "column" or "chop":

% cd /usr/man/man1
% egrep -i 'column|chop' *
awk.1:Add up first column, print sum and average:
colrm.1:colrm \- remove characters from specified columns within each line
  ...
cut.1:.IX  cut  ""  "\fIcut\fP \(em remove columns from file"
  ...

It's cut! Notice that awk also handles columns, but apropos doesn't say so.

(I cheated on that example: there were other ways to find cut -- using the synonym apropos field instead of apropos column, for instance. But this method does work in tougher cases.) To search the manual page files, you'll need to know where they're stored. There are lots of possibilities. If your system has an /etc/man.config file, it'll probably tell you. Otherwise, the directories /usr/man or /usr/share/man are good places to look. If the command is local, try /usr/local/man and maybe /opt (a big tree where find (Section 9.4) can help). If your system has fast find or locate (Section 9.18), try searching for man or */man*.

Your manpage files may be compressed (Section 15.6). In that case, use grep (Section 13.2) with the -Z option, grep -Z.

You'll probably find subdirectories with names like man1, man2, . . . and/or cat1, cat2, . . . Directory names like manN will have unformatted source files for section N; the catN directories have formatted source files. Or you may just find files named command.N, where N is 1 for section 1, 2 for section 2, and so on.

There are two types of manpage files: unformatted (shown in Section 3.22) and formatted. The unformatted pages are easier to search because none of the words will have embedded backspace characters. The previous example shows how. The unformatted pages have nroff commands and macros in them, though, which can make searching and reading tougher.

To search formatted pages, you'll want to strip the embedded backspace characters. Otherwise, grep might miss the word you want because it was boldfaced or underlined -- with backspaces in it. In the following example, a shell loop (Section 28.9) applies a series of commands to each file. First, col -b removes the overstriking. grep does a search (case insensitive, as before). Because grep is reading its standard input, it doesn't know the filename, so a little sed command adds the name to the start of every line grep outputs.

$ cd /usr/man/cat1

* Section 1.13

$ for file in *
> do col -b < $file | grep -i column | sed "s/^/${file}:/"
> done
awk.1:   Add up first column, print   sum and average:
   ...
cut.1:   Use cut to cut out columns from a table or fields from each
   ...

If your manpage files are compressed, replace col -b < $file with:

zcat $file | col -b

In Bourne shells, you can pipe the output of the loop to a pager (like less (Section 12.3)) to see the output a screenful at a time and quit (with q) when you're done. To do that, change the last line of the for loop to:

done | less

-- JP