How man Pages Work: Troubleshooting Tips


Contents

About this document
How man pages work under AIX
Common questions and problems

About this document

This document contains common questions about setting up man pages and applies to AIX Versions 3.2.x, 4.1.x and 4.2.x.


How man pages work under AIX

If the MANPATH environment variable is not set, the man command searches the following directories in this order to find data files:

   /usr/share/man/man   (NROFF format files) 
   /usr/share/man/cat   (ASCII format files) 
   /usr/lpp/info/data/ispaths file (pointer file for info explorer) 

To change the directories man should search, you can specify the path order with the MANPATH environment variable, such as (in ksh):

   export MANPATH=/usr/local/man:/usr/man 

This would cause man first to search /usr/local/man for man type subdirectories.

If the man command finds a file matching the request in any of the /usr/share/man/man# directories, it passes the file through the nroff text formatter and places the plain text version in one of the /usr/share/man/cat# directories (if the user has write permission to the cat directories). Then it displays the file.

If nothing is found in the man# directories, man looks in the cat# directories. If it finds a file of the proper name, it displays it.

AIX ships all of its operating system documentation in hypertext, for use with InfoExplorer. This information is stored in the /usr/lpp/info/lib directory structure in the aix.rom and aix.key files. After searching the man# or cat# directories, the man command looks in the /usr/lpp/info/data/ispaths file for stanzas similar to the following:

      ################################################ 
      #         info Using & Managing Database       # 
      ################################################ 
      id              1 
      glossary        TRUE 
      name            aix 
      title           Using, Managing and Commands: AIX and Extensions 
      sys             /usr/lpp/info/lib/%L/sys.sys 
  ->  key             /usr/lpp/info/lib/%L/aix/aix.key 
  ->  rom             /usr/lpp/info/lib/%L/aix/aix.rom 

For man to work, the files aix.rom and .key must exist where the key and rom entries are pointed. This can be a CD-ROM, a hard disk or an NFS mount. The %L variable stands for whatever language the LANG environment variable is set to. This file is set up correctly upon installation of the info databases and does not need to be manually configured.


Common questions and problems

You don't want InfoExplorer, only man pages

You only have ASCII terminals, and you don't want the ASCII version of InfoExplorer.

Solution:

If you only want man pages, you must first install InfoExplorer on the system, because the AIX man pages are a part of the InfoExplorer product. This does not mean you have to use InfoExplorer (ASCII or graphics), but it does enable you to access the man pages.

The man pages don't work

Solution:

After upgrade from AIX 3.2.x to 3.2.5, man pages quit working

Solution:

The upgrade instructions for AIX 3.2.5 and later versions say to save the /usr/lpp/info/data/ispaths file as it will be overwritten during the upgrade.

There is a long delay before the man command displays pages

How do you speed it up?

Solution:

It can sometimes take many seconds to display a manual page, particularly if the /usr/lpp/info is remotely mounted or is accessed from a CD-ROM drive. The system has to go to the slow CD-ROM drive, find the correct *.rom file and translate it. This is normal.

If you install the documentation to your hard disk (space permitting), it will operate somewhat faster. The bulk of the time is in parsing the large *.rom files for correct entries.

Since the man command checks the /usr/share/man/cat# directories before looking in the .rom file, you could place commonly accessed man pages in one of the appropriate cat# directories, and man will find it very quickly. You can manually do this for a single command like tar.

EXAMPLE for tar:

   man tar > /usr/man/cat2/tar.out 
   mv /usr/man/cat2/tar.out /usr/man/cat2/tar 
   chmod 444 /usr/man/cat2/tar 

The next time you use the man command to display the tar command, it will display in just a few seconds.

You could automate this process by creating a script that does this each time you do the man command on a new file. However, by default, only the root user has permissions to write to the man# and cat# directories.

man -k <pattern> or man -f <pattern> does not work

Solution:

The /usr/share/man/whatis file must exist before -k or -f will work. To create the file, execute: catman -w.

Since the whatis file indexes all of the articles the man command can find, you could use this as the basis for the man script described in the previous section.

InfoExplorer finds articles that man doesn't find

Solution:

There are at least 12 InfoExplorer databases, though the man command will only search in 4 or 5 of them. This is working as designed. The primary use of man is to conveniently access common articles you may want to reference, such as commands, subroutines, and files of the AIX operating system. Additional databases are available for other products (such as DCE), but man does not search these.

man uses "more" to page files. Can something else be used?

Solution:

By default man will use "more" to display items one page at a time. However, you can view man pages using other editors if you set your PAGER environment variable to the editor or pager desired. For example, in ksh, to use the page command:

   export PAGER=/usr/bin/page 



[ Doc Ref: 90605210314770     Publish Date: Jan. 30, 2001     4FAX Ref: 5102 ]