02/06/96, 4FAX# 5102 How Manpages Work: Troubleshooting Tips SPECIAL NOTICES Information in this document is correct to the best of our knowledge at the time of this writing. Please send feedback by fax to "AIXServ Information" at (512) 823-4009. Please use this information with care. IBM will not be responsible for damages of any kind resulting from its use. The use of this information is the sole responsibility of the customer and depends on the customer's ability to eval- uate and integrate this information into the customer's operational environment. ABOUT THIS DOCUMENT | This document contains common questions surrounding how to | set up man pages and is applicable to AIX versions 3.2 and | 4.1. A bibliography of how to setup man pages . . . . . . . 1 How do man pages work under AIX . . . . . . . . . . . . 1 Common questions and problems . . . . . . . . . . . . . 2 Don't want InfoExplorer, only man pages . . . . . . . 2 Man pages don't work . . . . . . . . . . . . . . . . 3 Just upgraded from 3.2.x to 3.2.5 but man pages quit working . . . . . . . . . . . . . . . . . . . . . . 3 | The man command takes forever to display . . . . . . 3 | The man -k or man -f does not work 4 | InfoExplorer finds articles that man doesn't find . . 4 Man uses "more" to page files . . . . . . . . . . . . 4 Reader's Comments . . . . . . . . . . . . . . . . . . . 5 A BIBLIOGRAPHY OF HOW TO SETUP MAN PAGES The following documents on man pages are available from 4FAX. Within the U.S., call 1-800-IBM-4FAX from a touch- tone phone. Outside the U.S., call (415) 855-4FAX from your fax machine phone. Internal to IBM, call T/L 465-4FAX. o man.pages.32.cmd (for aix 3.2) 4Fax # 2443 o man.pages.41.cmd (for aix 4.1) 4FAX # 4619 o techlib.install.cmd (for aix 3.2 and 4.1) 4FAX #5103 HOW DO MAN PAGES WORK UNDER AIX If the MANPATH environment variable is not set, the man command will search 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) How Manpages Work: Troubleshooting Tips 1 02/06/96, 4FAX# 5102 | 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 to first 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 will pass the | file through the nroff text formatter and place 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 will display the file. If nothing is found in the man# directories, man looks in the cat# directories and if it finds a file of the proper name, it will display 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: ################################################ # 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 In order for man to work, the files aix.rom and .key must exist where the key and rom entries are pointed. This can be a CDROM, a hard disk or a 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 Don't want InfoExplorer, only man pages I only have ascii terminals, and I 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 How Manpages Work: Troubleshooting Tips 2 02/06/96, 4FAX# 5102 | have to use InfoExplorer (ascii, or graphics); but it does | enable you to access the man pages. Man pages don't work | SOLUTION: | o First ensure that the InfoExplorer databases are | installed for the manual pages you are trying to access. o Check the ispaths file, and make sure that it points to where the files actually exist. o If a CDROM is used make sure that you can cd to the path shown in the ispaths filed. o Make sure that the LANG variable matches the directory name. Just upgraded from 3.2.x to 3.2.5 but man pages quit working SOLUTION: The upgrade instructions for 3.2.5 and later say to save the /usr/lpp/info/data/ispaths file as it will be overwritten during the upgrade. o If you saved the file, you need to rename it back to ispaths. o If you didn't save the file, copy the ispaths.full file over the ispaths file then check that it points to where the files really exist. | o If you just installed AIX, refer to the fax (listed | above) on installing man pages. | NOTE: If ALL was selected during the install, ALL does | not include the man pages. This is because the system | doesn't know which language you are going to use. | The man command takes forever to display | How do I 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 CDROM drive. It has to go to the slow CDROM | 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# direc- | tories before looking in the .rom file, you could place com- How Manpages Work: Troubleshooting Tips 3 02/06/96, 4FAX# 5102 | monly accessed man pages in one of the appropriate cat# | directories, and man will find it very fast. You can manu- | ally 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 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. | The man -k or man -f does not work | SOLUTION: | The /usr/share/man/whatis file must exist before the -k or | -f will work. To create the file, do: 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 that you may want to reference, such | as commands, subroutines, and files of the AIX operating | system. Additional databases are available for other pro- | ducts (such as DCE), but man does not search these. Man uses "more" to page files can I use something else? 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 How Manpages Work: Troubleshooting Tips 4 02/06/96, 4FAX# 5102 READER'S COMMENTS Please fax this form to (512) 823-4009, attention "AIXServ Informa- tion". You may also e-mail comments to: elizabet@austin.ibm.com. These comments should include the same customer information requested below. Use this form to tell us what you think about this document. If you have found errors in it, or if you want to express your opinion about it (such as organization, subject matter, appearance) or make sug- gestions for improvement, this is the form to use. If you need technical assistance, contact your local branch office, point of sale, or 1-800-CALL-AIX (for information about support offer- ings). These services may be billable. Faxes on a variety of sub- jects may be ordered free of charge from 1-800-IBM-4FAX. Outside the U.S. call 415-855-4329 using a fax machine phone. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you. NOTE: If you have a problem report or item number, supplying that number may help us determine why a procedure did or did not work in your specific situation. Problem Report or Item #: Branch Office or Customer #: Be sure to print your name and fax number below if you would like a reply: Name: Fax Number: ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ END OF DOCUMENT (how.manpages.work.cmd, 4FAX# 5102) How Manpages Work: Troubleshooting Tips 5