'\"macro stdmacro
.if n .pH g1.man @(#)man	40.8 of 8/10/89
.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
'\" macro stdmacro
.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
.\"
.nr X
.if \nX=0 .ds x} man 1 "BSD Compatibility Package " "\&"
.if \nX=1 .ds x} man 1 "BSD Compatibility Package "
.if \nX=2 .ds x} man 1 "" "\&"
.if \nX=3 .ds x} man "" "" "\&"
.TH \*(x}
.SH NAME
\f4man\f1 \- display reference manual pages; find reference pages by keyword
.SH SYNOPSIS
\f4/usr/ucb/man\f1
[
\f4\-\f1
] [
\f4\-t\f1
] [
\f4\-M\f2 path\f1
] [
\f4\-T\f2 macro-package\f1
] [\|[
.I section
]
.IR title .\|.\|.\|]
.ti +3
.IR title \|.\|.\|.
.br
\f4/usr/ucb/man\f1
\f1[\|\f4\-M\f1
.IR path "\|]"
\f4\-k\f2 keyword\f1
\&.\|.\|.
.br
\f4/usr/ucb/man\f1
\f1[\|\f4\-M\f1
.IR path "\|]"
\f4\-f\f2 filename\f1
\&.\|.\|.
.SH DESCRIPTION
.P
The
\f4man\f1
command displays information from the
reference manuals.
It can display complete manual pages that you select by
.IR title ,
or one-line summaries selected either by
.I keyword
\f1(\f4\-k\f1),
or by the name of an associated file
\f1(\f4\-f\f1).
.P
A
.IR section ,
when given, applies to the
.I titles
that follow it on the command line (up to the next
.IR section ,
if any).
\f4man\f1
looks in the indicated section of the manual for those
.IR title s.
.I section
is either a digit (perhaps followed by a single letter indicating
the type of manual page), or one of the words
\f4new\f1,
\f4local\f1,
\f4old\f1,
or
\f4public\f1.
If
.I section
is omitted,
\f4man\f1
searches all reference sections
(giving preference to commands over functions)
and prints the first manual page it finds.
If no manual page is located,
\f4man\f1
prints an error message.
.P
The reference page sources are typically located in the
\f4/usr/share/man/man?\f1
directories.
Since these directories are optionally installed,
they may not reside on your host; you may have to mount 
\f4/usr/share/man\f1
from a host on which they do reside.
If there are preformatted, up-to-date versions in
corresponding
\f4cat?\f1
or
\f4fmt?\f1
directories,
\f4man\f1
simply displays or prints those versions.
If the preformatted
version of interest is out of date or missing,
\f4man\f1
reformats it prior to display.
If directories for the
preformatted versions are not provided, 
\f4man\f1
reformats a page whenever it is requested; it uses a temporary
file to store the formatted text during display.
.P
If the standard output is not a terminal, or if the
\f4\-\f1
flag is given,
\f4man\f1
pipes its output through
\f4cat\f1.
Otherwise,
\f4man\f1
pipes its output through
\f4more\f1
to handle paging and underlining on the screen.
.P
The following options are available:
.TP
\f4\-t\f1
\f4man\f1
arranges for the specified manual pages to be
\f4troff\f1ed
to a suitable raster output device (see
\f4troff\f1
or
\f4vtroff\f1).
If both the
\f4\-\f1
and
\f4\-t\f1
flags are given,
\f4man\f1
updates the
\f4troff\f1ed
versions of each named
.I title
(if necessary), but does not display them.
.TP
\f4\-M\f2 path\f1
Change the search path for manual pages.
.I path
is a colon-separated list of directories that contain manual page
directory subtrees.
When used with the
\f4\-k\f1
or
\f4\-f\f1
options, the
\f4\-M\f1
option must appear first. 
Each directory in the
.I path
is assumed to contain subdirectories of the form
\f4man[1-8l-p]\f1.
.TP
\f4\-T\f2 macro-package\f1
\f4man\f1
uses
.I macro-package
rather than the standard
\f4\-man\f1
macros defined in
\f4/usr/ucblib/doctools/tmac/tmac.an\f1
for formatting manual pages.
.TP
\f4\-k\f2 keyword .\|.\|.\f1
\f4man\f1
prints out one-line summaries from the
\f4whatis\f1
database (table of contents) that contain any of the given
.IR keyword s.
.TP
\f4\-f\f2 filename .\|.\|.\f1
\f4man\f1
attempts to locate manual pages related to any of the given
.IR filename s.
It strips the leading pathname components from each
.IR filename ,
and then prints one-line summaries containing the resulting
basename or names.
.SH "MANUAL PAGES"
.P
Manual pages are
\f4troff\f1
or 
\f4nroff\f1
source files prepared with the
\f4\-man\f1
macro package.
.P
When formatting a manual page,
\f4man\f1
examines the first line to determine whether
it requires special processing.
.SS "Preprocessing Manual Pages"
.P
If the first line is a string of the form:
.IP
\f4\'\|\e"\0 \f2X\fP
.P
where
.I X
is separated from the the
`\f4"\fP'
by a single
.SM SPACE
and consists of any combination of characters in the following list,
\f4man\f1
pipes its input to
\f4troff\f1
or
\f4nroff\f1
through the corresponding preprocessors.
.sp .5
.RS
.PD 0
.TP
\f4e\f1
\f4eqn\f1,
or
\f4neqn\f1
for
\f4nroff\f1
.TP
\f4r\f1
\f4refer\f1
.TP
\f4t\f1
\f4tbl\f1,
and
\f4col\f1
for
\f4nroff\f1
.PD
.RE
.P
If
\f4eqn\f1
or
\f4neqn\f1
is invoked,
it will automatically read the file
\f4/usr/ucblib/pub/eqnchar\f1
[see \f4eqnchar\f1(7)].
.SH ENVIRONMENT
.TP 15
\f4MANPATH\fP
If set,
its value overrides
\f4/usr/share/man\f1
as the default search path.
The
\f4\-M\f1
flag, in turn, overrides this value.
.TP
\f4PAGER\fP
A program to use for interactively delivering
\f4man\f1's
output to the screen.
If not set,
\f1`\f4more \-s\f1'
(see
\f4more\f1)
is used.
.TP
\f4TCAT\fP
The name of the program to use to display
\f4troff\f1ed
manual pages.
If not set,
\f1`\f4lp \-Ttroff\f1'
(see \f4lp\f1)
is used.
.TP
\f4TROFF\fP
The name of the formatter to use when the
\f4\-t\f1
flag is given.
If not set,
\f4troff\f1
is used.
.SH FILES
.PD 0
.TP 25
\f4/usr/share/man\f1
root of the standard manual page directory subtree
.TP
\f4/usr/share/man/man?/*\f1
unformatted manual entries
.TP
\f4/usr/share/man/cat?/*\f1
\f4nroff\f1ed
manual entries
.TP
\f4/usr/share/man/fmt?/*\f1
\f4troff\f1ed
manual entries
.TP
\f4/usr/share/man/whatis\f1
table of contents and keyword database
.TP
\f4/usr/ucblib/doctools/tmac/man.macs\f1
standard
\f4\-man\f1
macro package
.TP
\f4/usr/ucblib/pub/eqnchar\f1
.PD
.SH "SEE ALSO"
\f4apropos\fP(1),
\f4cat\fP(1),
\f4catman\fP(1M),
\f4col\fP(1),
\f4eqn\fP(1),
\f4nroff\fP(1),
\f4refer\fP(1),
\f4tbl\fP(1),
\f4troff\fP(1),
\f4whatis\fP(1),
\f4eqnchar\fP(7).
.P
\f4col\fP(1),
\f4lp\fP(1),
\f4more\fP(1)
in the \f2User's Reference Manual\f1.
.SH NOTES
The manual is supposed to be reproducible
either on a phototypesetter or on an
.SM ASCII
terminal.
However,
on a terminal some information
(indicated by font changes,
for instance)
is necessarily lost.
.P
Some dumb terminals cannot process the vertical motions produced
by the
\f4e\f1
\f1(\f4eqn\f1(1))
preprocessing flag.
To prevent garbled output on these terminals,
when you use
\f4e\f1
also use
\f4t\f1,
to invoke
\f4col\f1(1)
implicitly.
This workaround has the disadvantage of eliminating superscripts and
subscripts \(em even on those terminals that can display them.
.SM CTRL-Q
will clear a terminal that gets confused by
\f4eqn\f1(1)
output.
