BSD DevCenter
oreilly.comSafari Books Online.Conferences.


Read The Friendly Manpage! -- Part Two
Pages: 1, 2

Now, let's go back to the /usr/share/man directory to look at the difference between the unformatted manpages contained in the man subdirectories and the formatted manpages contained in the cat subdirectories. Since all of the manpages have been gzipped, you will have to first uncompress the data using the gunzip utility, then use cat or more to view the data, then finally remember to re-compress the file so you can continue to conserve disk space. Fortunately, the zcat utility seamlessly does all three of these steps for you.

Let's zcat the whatis manpage, as it is a nice short manpage that fits on one screen. We'll start with the unformatted version:

zcat man1/whatis.1

View the output of this command here.

Notice that this doesn't look anything like the whatis manpage as you are used to seeing it. (If you forget what the whatis manpage looks like, do a man whatis.) Instead, this file contains remarks and formatting commands along with the actual data. Let's compare this to the pre-formatted version contained within the cat subdirectory:

zcat cat1/whatis.1

View the output of this command here.

Notice that the pre-formatted version looks like the manpage you are used to seeing, minus the highlighting. However, something very interesting happens if we try to save a formatted manpage into a file. Let's send the output of zcatting the formatted whatis manpage to a test file in our home directory:

zcat cat1/whatis.1 > ~/test

Now, let's view the test file using the cat utility:

cat ~/test

Your test file should look exactly like the zcatted whatis.1 file. Now, send the test file to the more paging utility:

more ~/test

Your results should look exactly like a manpage, with highlighting included. Finally, open up the test file using your favorite text editor; I'll use Pico, but you can use any editor.

pico ~/test

View the output of this command here.

Yuck, what a mess. It's funny how a lot of ^H characters can make a file so unreadable. However, if you look very carefully, and mentally try to remove the ^H's, you should be able to recognize the text in your file. In case you're wondering, ^H is the control character for highlighting text.

We've just discovered an interesting difference in functionality between the cat utility, the more utility, and an editor. By default, cat ignores control characters, more interprets control characters, and text editors display control characters. Thus we have an unhighlighted but readable file with cat, a highlighted file with more, and a mess with a text editor.

You can force cat to display control characters instead of ignoring them by using a switch. Try this:

cat -v ~/test

Your output should display all of the ^H characters, just like the text editor did.

Understanding this behavior will come in handy if you ever want to send a manpage to a file: Perhaps you want to transfer some manpages to your non-Unix laptop or want to include some interesting snippets of a manpage when replying to an e-mail. If you just redirect the output of the man command to a file like this:

man whatis > ~/test

your resulting file will contain all of those irritating ^H characters. However, if you pipe the output through the col command before sending it to your file, you will lose the ^H characters. Try it:

man whatis | col -b > ~/test

then send ~/test to your favorite text editor to see the difference.

If you read the manpage for the col command, you'll discover why this works; the col command discards all of the control characters it doesn't recognize. And, fortunately for us, col doesn't recognize that many control characters.

This trick is also very handy if you ever transfer an ASCII file from an MS-DOS-based operating system to your FreeBSD system. If you've ever done this before, you've discovered that MS-DOS-based operating systems put a ^M at the end of every line to indicate the carriage return. You could use your arrow keys to navigate to each of these characters so you can press the delete key, but it is much easier to do this:

col -b < dosfile > unixfile

This command tells col to strip the control characters from a file called dosfile and then send the results to a new file called unixfile.

Or, if it's too late and you've already opened up the file in vi, try this:

:%! col -bx

This will remove all of those pesky ^M or ^H characters without having to leave vi. We'll save the explanation of how that works for a later article dealing with the vi editor.

Now we've finally reached the part of the article where we can tie together all of this stuff to better understand how the man command works. When you type:

man name_of_manpage

the man utility searches the /usr/share/man subdirectories, in order, for the first reference of the manpage you wish to view. You can alter this default behavior like so:

man -a name_of_manpage

which will force man to read all of the subdirectories; this switch is useful if you think a manpage is in more than one section in the manual and you wish to view them all.

If man doesn't find the manpage here, it will then look in /usr/local/man. If you do a listing of this directory and its subdirectories, you will find the manpages for the programs you installed yourself: i.e., any ports or packages that you built.

Once man has found the manpage, the formatted copy is sent to a pager so it can be displayed on your screen one page at a time. If you are using FreeBSD 4.0 or earlier, the default pager is the more utility. If you are using FreeBSD 4.1 or later, the default pager is the less utility. In true Unix style, the less utility actually offers more functionality than the more utility. Regardless of which pager your system uses, the pager will correctly interpret the ^H characters to expose the highlighted text. If you prefer to read your manpages without that glaring white text, you can start your manpage like so:

man whatis | col -b | more

You can substitute the word more with less if you prefer the less paging utility.

We've covered a lot of ground in the last couple of articles. In the next few articles I want to discuss some of the neat utilities that can be built using the ports collection.

Dru Lavigne is a network and systems administrator, IT instructor, author and international speaker. She has over a decade of experience administering and teaching Netware, Microsoft, Cisco, Checkpoint, SCO, Solaris, Linux, and BSD systems. A prolific author, she pens the popular FreeBSD Basics column for O'Reilly and is author of BSD Hacks and The Best of FreeBSD Basics.

Read more FreeBSD Basics columns.

Discuss this article in the Operating Systems Forum.

Return to the BSD DevCenter.


Sponsored by: