Hack 91 Get the Most Out of Manpages

Now that you know how to create your own manpages, you'll want to know how to get the most out of your manpage viewing.

Since most documentation on Unix systems lives within manpages, it pays to know how to get the most out of your manpage-reading experience. How do you make sure you're aware of all of the manpages installed on a system? How do you zero in on the information you need, without having to read an entire manpage? Yes, it's a great experience to read all of man tcsh at least once in your life, but you don't want to do that when you're only interested in a certain shell variable.

9.4.1 Finding Installed Manpages

You may have noticed that, by default, whatis [Hack #13] doesn't find custom manpages or those installed by third-party applications. Not only is this inconvenient, but it can also prevent your users from getting the most out of the applications installed on a system.

Remember /etc/manpath.config from [Hack #90] ?

% grep MAP /etc/manpath.config # MANPATH_MAP    path_element        manpath_element MANPATH_MAP      /bin                /usr/share/man MANPATH_MAP      /usr/bin            /usr/share/man MANPATH_MAP      /usr/local/bin      /usr/local/man MANPATH_MAP      /usr/X11R6/bin      /usr/X11R6/man

The makewhatis command actually creates the whatis database and, by default, makewhatis reads only /usr/share/man. It'll skip any manpages in /usr/local/man and /usr/X11R6/man, because it doesn't know they exist!

To gather in those missing manpages, pass these extra directories to makewhatis:

# makewhatis /usr/local/man /usr/X11R6/man #

The superuser can run this command at any time, say, after installing new software. If you're a forgetful or appropriately lazy superuser, consider adding this as a regular cron job.

Now users will be aware of all of the manpages on the system.

9.4.2 Navigational Tricks

There's nothing worse than wading through dozens of pages of information that are irrelevant to your question. Why wade when you can zero in on the information you want? When you read a manpage, man sends the text to your default pager a program designed for speedy navigation.

FreeBSD 4.1 replaced the more pager with less. less is chock-full of useful and configurable navigation tricks, so this is a case where less really is more.

Even though your .cshrc file and man man show more as your default pager, remember more is now really less.

less even comes with its own help system containing an itemized list of all of its neat tricks. Whenever you're in a manpage or, for that matter, in any file you've sent to a pager simply type h to see the help screen.

I won't repeat that help here, but Table 9-2 shows some navigational keys to get you moving around.

Table 9-2. less navigation keys

Key	Behavior
Enter	Scrolls down one line
y	Scrolls up one line (think "yikes, I missed it!")
Spacebar	Scrolls down one page
b	Scrolls up (back) one page
g	Goes to the beginning of the manpage
q	Quits the pager (so you don't have to read the whole manpage)

9.4.3 Customizing less

It's well worth your time to experiment with how less formats its output. For example, when you open a manpage, the prompt at the bottom of your screen indicates how many bytes of that manpage you've read. If you type -m, you'll change to the short prompt, a single colon (:). -M changes to the long prompt, which displays the line range you're currently viewing.

If you really want to know what line you're on, try -N. Read up on -P to create your own custom prompt string.

You can also configure how many lines you scroll, also known as the window size. Here I'll change the window size to 10 lines:

-z Scroll window size: 10 Scroll window size is 10 lines  (press RETURN)

Now when I press my spacebar, I'll scroll down 10 lines instead of the entire screen.

If you experiment with the dozens of options listed in help, you'll find that they only last for the contents of the current manpage. If you find options you like, make them permanent by adding them to your ~/.cshrc file. Here I'll permanently configure the -M, or long, prompt and a window size of 10:

setenv LESS Mz10

Note that I've simply created a string of desired options, minus the switch indicator (-). I'll also have to change the line setenv PAGER more to setenv PAGER less, so that applications that honor my pager choice will use less instead of more. To test your changes, force the shell to reread its configuration file, then open up a manpage:

% source ~/.cshrc % man man

That manpage should now have a customized prompt and window.

9.4.4 Searching Text

Now that you can move around, you'll want to search for the information you need. After all, you're usually looking for something specific when you read a manpage. Fortunately, less provides an easy-to-use search feature. Press /, the forward slash. Your prompt will change to / while less waits for you to type in a search string of one or more words.

Consider adding I to the less configuration in your .cshrc file to enable case-insensitive searching. Without it, searching for /long format in man ls will skip the desired section, as it is entitled The Long Format.

Press Enter once you've typed in a search string, and less will take you to the first occurrence of that string. Repeatedly pressing n will scroll you through the next occurrences. Press N to scroll back through your search results. If you change your mind and want to search for something else, press /.

Suppose you're reading or searching along and find an interesting bit you'll want to refer to again. Mark your current position with:

m mark: a

Here I've marked my position with the letter a. I'll then carry on with reading the results of the rest of my search. To return to that position, I simply type a single quote and the position marker ('a). You can mark as many as 26 positions (one for each lowercase letter).

You can also use two single quotes ('') to toggle back and forth between two positions. For example, I may be in man systat and can't believe the display includes a pigs option. So I do a search for /pigs and read up on that type of display. '' will bring me back to the original line that piqued my curiosity. Another '' will put me back at my search result.

9.4.5 See Also

• manpath

• man man

• man makewhatis

• man less