[Chapter 50] 50.6 Searching Online Manual Pages
Author: Jerry Peek, Tim O'Reilly & Mike Loukides
Date: 1998-08-04T21:56:55Z

#

| Chapter 50 Help--Online Documentation, etc. |

## 50.6 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 (50.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 apropos (50.2), 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 (50.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, but 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 (17.4) can help). If your system has fast find or locate (17.18), try searching for `man` or `*/man*`.

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 article 50.11) and formatted (with overstriking, as in article 43.18). The unformatted pages are easier to search because none of the words will have embedded backspace characters. The example above shows how. The unformatted pages have nroff (43.13) 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 example below, a shell loop (9.11, 9.12) applies a series of commands to each file. First, col -b (43.18) 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
    $ 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
       ...

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

>     done | less

- JP

50.5 whereis: Finding Where a Command Is Located |  | 50.7 How UNIX Systems Remember Their Name