man(C) 06 January 1993 man(C) Name man - print reference pages in this guide Syntax man [ -afbcw ] [ -tproc ] [ -ppager ] [ -ddir ] [ -Tterm ] [ section ] [ title ] /usr/lib/manprog file Description The man program locates and prints the named title from the designated reference section. For historical reasons, ``page'' is often used as a synonym for ``entry'' in this context. Since UNIX commands are given in lowercase, the title is almost always entered in lowercase. If no section is specified, the whole guide is searched for title and the first occurrence of it is printed. You can search for a group of sections by separating the section names with colons (:) on the command line. There are instances where title contains mixed upper and lowercase letters. The Intro pages are one such example. Others are to be found in sections covering internal routines such as (K) and (S). The options and their meanings are: -a ``All'' mode. Displays all matching titles. Incompatible with the -f option. -f ``First'' mode. Displays only the first matching title. Incom- patible with -a option. This is the default mode for man. -b Leaves blank lines in output. nroff(CT) pads entries with blank lines for line printer purposes. man normally filters out these excess blank lines. Normally, man does not display more than 2 consecutive blank lines. The -b flag leaves blank lines in the CRT output. -c Causes man to invoke col(C). Note that col is invoked automat- ically by man unless term is one of the following: 300, 300s, 450, 37, 4000a, 382, 4014, tek, 1620, or X. -w Prints on the standard output only the pathnames of the entries. -tproc Indicates that if an unprocessed manual page is available, it is to be passed to proc for formatting. proc can be any command script in /usr/man/bin or an absolute filename of a text pro- cessing program elsewhere on the system, for example /bin/nroff. The scripts in /usr/man/bin invoke the actual pro- cessing programs with the correct flags and arguments. The default processor is /usr/man/bin/nr, which invokes /bin/nroff and produces output that safely prints on any terminal. The text is also preprocessed by eqn(CT) and tbl(CT) as a default. -ppager Selects paging program pager to display the entry. Paging sys- tems such as more(C), pg(C), cat(C), or any custom pagers that you may have are valid arguments for this flag. The default pager, pg, is set in /etc/default/man. -ddir Specifies directory dir to be added to the search path for entries. You can specify several directories to be searched by separating the directory names with colons (:) on the command line. -Tterm Format the entry and pass the given term value to the pro- cessing program, then print it on the standard output (usually, the terminal), where term is the terminal type (see term(M) and the explanation below). Section names The names and general descriptions of the available manual sections are: ADM System administration C Commands CP Commands for programmers (Development System) DOS DOS routines and libraries (Development System) F File formats FP File formats for programmers (Development System) HW Hardware dependent features K Device driver routines and libraries M Miscellaneous S Development System routines and libraries XNX XENIX cross development (Development System) LOCAL Local utilities for your system You can add other section names as you wish. Each new section, however, must follow the standard section directory structure. The LOCAL directory is shipped without contents, as no LOCAL manual pages are included. You will only have access to the Development System and Device Driver manual pages if the corresponding modules have been installed on your system. /usr/man directory structure The source files for the man program are kept in the directory /usr/man. Each man section is comprised of two directories, and there is a direc- tory called bin for programs and shell scripts related to man. There is also an index file called index in /usr/man. This index is a list of all UNIX commands and their sections. Each manual section has two directories in /usr/man. These directories are called man and cat, plus the name of the section as a suffix. For example, the ``C'' manual section comprises of two directories, man.C and cat.C, both located in /usr/man. The unprocessed source text is in the man directory and the printable processed output is in the cat directory. When a title is requested, both directories are checked. The most recent copy of the manual page is used as the current copy. If the most recent title is in the source text directory and it is processed by the default processor with the default terminal type, a display copy of the output is placed in the cat direc- tory for future use. Note that a file that must be processed takes longer to appear on the screen than a display copy. Environment variables There is a shell environment variable for use with the man utility. This variable is called MANPATH and it is used to change or augment the path man searches for entries. Multiple directories set with this variable must be delimited by colon characters (:). If the MANPATH environment variable is present, the directories are searched in the order that they appear. /usr/man must appear in the MANPATH list to be included. If you set this environment variable, it supersedes the MANPATH entry in the /etc/default/man file. Alternate subdirectories are expected to have the same form as the default directories in /usr/man. /etc/default/man There is a file called man in the /etc/default directory that contains the default settings for the man utility. The following options are set in /etc/default/man: PAGER=/usr/bin/pg MANPATH=/usr/man TERM=lp ORDER=ADM:C:S:CP:M:F:HW:DOS:LOCAL MODE=FIRST PROC=nr You can select a different paging system, search path, terminal type, search order, mode, and processor for the man system by changing the in- formation in this file. To change the search order for manual sections, edit the list following the ORDER variable. Be certain the section names are separated with colons (:). Section names not present in ORDER are searched in arbitrary order after those specified in /etc/default/man. Creating new manual entries You can create new manual pages for utilities and scripts that you have developed. Use an existing manual page as an example of manual page structure. Use the man macros to format your manual page. For more infor- mation, refer to the nroff(CT) manual page. You must be logged in as root (the ``super user'') to place a new manual page in your /usr/man directory structure. Place your new page in /usr/man/man.LOCAL while logged in as root and view it using the man com- mand, since only root has write permission for the cat-able directories. Once man has produced the cat-able output, any user can view the new page in the same manner as any other on line manual page. Additionally, you can create your own custom sections by creating another manual directory and putting it in the MANPATH. For example, if subdirec- tories man.X and cat.X are present, then man recognizes that ``X'' is a valid manual section. If you wish to use another text processing program (such as troff(CT)) to process your custom manual pages, use the -tproc flag of man. proc can be any shell script in /usr/man/bin. To place a cat-able copy of the manual page in the cat directory, use the tee(C) command to send the output to a file, as well as to the standard output. Your command should have the form: man -tproc filename | tee pathname In the above example, proc is the text processing script, filename is the manual page source file, and pathname is the path of the directory for the cat-able output. Custom manual sections can have an index, if the format is the same as the index in /usr/man. man uses the index to locate multiple commands that are listed on the same page as well as commands that have pages in several different sections. The man macro package The man macro package is located in /usr/lib/macros/an. There are 15 basic macros in the package. Here is a table of the macros and brief descriptions of their functions: _________________________________________________________________________ Macro Description _________________________________________________________________________ .TH title Title heading .SH title Section heading .SS title Subsection heading .SM text Reduce point size .PP New paragraph .IP Indented paragraph .HP Hanging paragraph .TP Tagged paragraph .RS n Relative indent .RE Release relative indent .I text Italic font .B text Bold font .R text Roman font .PM Proprietary mark (copyright) See also eqnchar(CT), nroff(CT), tbl(CT), troff(CT), environ(M) and term(F). Notes All entries are supposed to be reproducible either on a typesetter or on a terminal. However, on a terminal some information, such as eqn(CT) and tbl(CT) output, is either lost or approximated as it cannot be exactly reproduced. In order to make use of eqnchar, nroff, tbl, and troff, it is first necessary to obtain and install the UNIX Text Processing System (avail- able separately). Value added man is an extension of AT&T System V provided by The Santa Cruz Opera- tion, Inc.