MAN(C) UNIX System V
Name
man - prints 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
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.
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. Incompatible with -a option. This is the
default mode for man(C).
-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 automatically by man unless term is one
of the following: 300, 300s, 450, 37, 4000a,
382, 4014, tek, 1620, and 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
processing program elsewhere on the system, for
example /bin/nroff.
The scripts in /usr/man/bin invoke the actual
processing 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 systems 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(C), 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 processing 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
M Miscellaneous
F File Formats
HW Hardware Dependent
S Subroutines and Libraries
CP Programming Commands
DOS DOS Subroutines and Libraries
LOCAL Local utilities for your system
You can add other section names as you desire. 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.
/usr/man Directory Structure
The source files for the man(C) program are kept in the
directory /usr/man. Each man section is comprised of two
directories, and there is a directory called bin for
programs and shell scripts related to man(C). 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 is
comprised 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 directory 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(C) utility. This variable is called MANPATH and it is
used to change or augment the path man(C) 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(C) system by changing the information 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 information, 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(C) command, 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 subdirectories man.X and cat.X are
present, then man(C) 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(C) 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),
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.
(printed 2/15/90) MAN(C)