[Chapter 50] 50.3 apropos on Systems Without apropos
Author: Jerry Peek, Tim O'Reilly & Mike Loukides
Date: 1998-08-04T21:56:50Z

#

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

## 50.3 apropos on Systems Without apropos

I was just asked to write an article about how to simulate apropos on systems that don't have it. I have to confess that I've never faced this problem. But I was able to come up with a solution. Your mileage may vary - particularly since different UNIX implementations have different ways of storing their manual pages.

The solution has two parts. First, you need a script that builds an index; that's better than grepping through every manual page in the world. [ Not always (50.6). `;-)` -JP ] Then you need an apropos alias that automatically searches your index file. Here's the script to build the index file:

    for

    sed

    `...`

    col
    egrep
    uniq

    done >
    #!/bin/sh
    # manindex: Generate a list of topic lines that you can grep through.
    # Then create 'apropos' and other aliases to search the list.
    # Run this periodically-once a month should suffice
    mandir=/usr/share/man     # where the manual pages are stored
    manlist="cat1 cat2 cat3"  # list particular directories you care about
    indexfile="/home/mike/manindex.txt"

    rm -f $indexfile
    for directory in $manlist
    do
            cd $mandir/$directory
            # the sed command turns filenames into "manual page" names
            # e.g., converts sed.1.z to sed.
            # BUG:  won't handle names like a.out.4.Z correctly
            for manpage in `ls | sed -e 's/\..*$//g'`
            do
                    # use man to unpack the manual page; it might be compressed
                    # use col to strip garbage characters
                    # egrep looks for spaces, manual page name, and dash
                    man $manpage | col -b -x | egrep "^ +$manpage.* - " | uniq
            done
    done > $indexfile

This script goes through every directory in which manual pages are stored. It strips all suffixes from the filenames, and then uses man to print the actual manual page. This is better than trying to look at the raw manual pages themselves because some vendors don't provide the raw manual pages. If you let man give you the page you want, you'll always find it. [2] The col command strips out boldfacing, underlining, and other monstrosities that will confuse grep. Finally, egrep looks for lines to put in the index. It's not as fussy as the BSD catman program (which mkindex is emulating), so it will find a fair number of lines that don't belong; but we think this is only a mild flaw.

> [2] If you have the source files for the manual page online, rather than pre-formatted files, you might want to rewrite the script to search them directly. It will be a lot faster.

Before you can use this script you'll have to substitute definitions for three variables:

mandir

  The top-level directory in which manual pages are stored. Often /usr/man, but it may be different on your system.

manlist

  Subdirectories containing the manual pages you care about. You'll probably want the directory in which user-level commands are stored, as a minimum. This level of directory naming may be radically different on different systems. I think this script is flexible enough to handle all the variations I can remember; if it can't, you'll have to hack it up a bit.

indexfile

  The file in which you want to keep your index (the output of this script).

Expect manindex to run for a long time; several minutes or more, depending on how thorough you want to be. Fortunately, you don't need to do this very often: once to get started, and then once a month (or so) to pick up any "stray" manual pages that someone else may have added. If you want to speed the task up, remember that you can skip any sections of the manual that you're not interested in by defining manlist appropriately. For example, if you're not interested in section 2 of the manual, just leave cat2 out of the list.

Once you've created the index, the rest of the problem is easy. Just make yourself an apropos alias (10.2) and add it to your .cshrc file:

>     alias apropos "grep -i \!$ /home/mike/manindex.txt"

Here's what its output looks like:

>     % apropos search
>     acctcom - search and print process accounting file(s)
>     egrep - search a file for a pattern using full regular expressions
>     fgrep - search a file for a character string
>     fmlgrep - search a file for a pattern
>     grep - search a file for a pattern
>     pathconv - search FMLI criteria for filename

As I pointed out, this isn't perfect. But I think it's a reasonable substitute.

- ML

50.2 The apropos Command |  | 50.4 whatis: One-Line Command Summaries