gno/usr.bin/man/man.1

.\" This man page copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\" While this manual page is based on one from UCB, the included
.\" C source, makefile, and executables are copyright (c) 1995-1998
.\" by Devin Reade <gdr@trenco.gno.org>.  All rights reserved.
.\"
.TH MAN 1 "28 March 1998" GNO "Commands and Applications"
.SH NAME
man \- display reference manual pages; find reference pages by keyword
.SH SYNOPSIS
.B man
.RB "[\|" \-  "\|]"
.RB "[\|" \-t "\|]"
.RB "[\|" \-M
.IR path "\|]"
.RB "[\|" \-T
.IR macro-package "\|]"
.RI "[\|" section "\|] " title "
.br
.B man
.RB "[\|" \-M
.IR path "\|]"
.B \-k
.I keyword
\&.\|.\|.
.br
.B man
.RB "[\|" \-M
.IR path "\|]"
.B \-f 
.I filename
\&.\|.\|.
.SH DESCRIPTION
This manual page documents
.BR man
version 3.0.
.LP
.B man
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
.RB ( \-k ),
or by the name of an associated file
.RB ( \-f ).
.LP
A
.IR section ,
when given, applies to the
.I title
that follows it on the command line.
.B man
looks in the indicated section of the manual for that
.IR title .
.I section
is either a digit (perhaps followed by a single letter indicating
the type of manual page), or one of the words
.BR new ,
.BR local ,
.BR old ,
or
.BR public .
The
abbreviations
.BR n ,
.BR l ,
.B o
and
.B p
are also allowed.
If
.I section
is omitted,
.B man
searches all reference sections
(giving preference to commands over functions).
If more than one manual page exists for the specified
.IR title ,
each page is displayed in the order in which it is found.  The
user is given the option of exiting after each page is displayed.
If no manual page is located,
.B man
prints an error message.
.LP
The reference page sources are typically located in the
.BR /usr/man/man?
directories.
If there are preformatted, up-to-date versions in
corresponding
.B cat?
or
.B fmt?
directories,
.B man
simply displays or prints those versions.
If the preformatted
version of interest is out of date or missing,
.B man
reformats it prior to display.
If directories for the
preformatted versions are not provided, 
.B man
reformats a page whenever it is requested.
.LP
If the standard output is not a terminal, or if the
.RB ` \- '
flag is given,
.B man
pipes its output through
.BR cat (1V).
Otherwise,
.B man
pipes its output through
.BR more (1)
to handle paging and underlining on the screen.
.SH OPTIONS
.IP \fB\-t\fP
.B man
arranges for the specified manual pages to be
.BR troff ed
to a suitable raster output device (see
.BR troff (1)
or
.BR vtroff (1)).
If both the
.B \-
and
.B \-t
flags are given,
.B man
updates the
.BR troff ed
versions of each named
.I title
(if necessary), but does not display them.
.IP "\fB\-M\fP \fIpath\fP"
Change the search path for manual pages.
.I path
is a colon- or space-separated list of directories that contain manual page
directory subtrees.
For example,
.B /usr/man/u_man:/usr/man/a_man
makes
.B man
search in the standard System V locations.
The space delimiter is provided for compatibility with GS/OS's
use of the colon as a pathname component delimiter.  If the search
path contains no spaces nor
.B /
characters (such as
.BR :usr:local:man ),
it is assumed to be a single path, not a list of paths.
If spaces are used as delimiters, remember to quote
.I path
from the shell.
Each directory in the
.I path
is assumed to contain subdirectories of the form
.BR man[1-8l-p] .
.IP "\fB\-T\fP \fImacro-package\fP"
.B man
uses
.I macro-package
rather than the standard
.B \-man
macros defined in
.B /usr/lib/tmac/tmac.an
for formatting manual pages.
.IP "\fB\-k\fP \fIkeyword .\|.\|.\fP"
.B man
prints out one-line summaries from the
.B whatis
database (table of contents) that contain any of the given
.IR keyword s.
The
.B whatis
database is created using the
.BR makewhatis (8)
command.
.IP "\fB\-f\fP \fIfilename .\|.\|.\fP"
.B man
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.
This option also uses the
.B whatis
database.
.br
.ne 7
.SH "MANUAL PAGES"
.LP
Manual pages are either
.BR nroff (1)/ troff (1)
source files prepared with the
.B \-man
macro package, or
.BR aroff (1)
source files prepared with
.B "Appleworks GS"
(tm) or a compatible word processor.
.SS "Referring to Other Manual Pages"
Other manual pages can be referenced in one of two ways, depending on
whether the target manual page is an
.BR aroff
or
.BR nroff
source file.
.LP
For
.BR aroff
source files, a "link" may be made by creating a file ending in
.BR ".l"
(that's a dot-ell).  The file must contain a single line consisting
of the pathname of the target
.BR aroff
source file.
An intentional design limitation was made that disallows this form
of "link" in the
.BR manl
(that's man-ell) subdirectory.
.LP
For
.BR nroff
source files, a "link" may be made by creating a file containing
the
.BR nroff
source (\fB\.so\fP) command.  This file should have the same suffix
as the target
.BR nroff
source file.
.B man
does not itself do any processing of the source command.
.LP
With both types of "links" the pathname may be either a full- or
partial-pathname.  In the latter case, the pathname must be relative
to the root of the manual page directory subtree.
.LP
.B man
processes the indicated file in place of the current one.
The reference must be expressed as
a pathname relative to the root of
the manual page directory subtree.
.SS "Preprocessing Manual Pages"
If the first line is a string of the form:
.nf

     \fB'\|\e"\0 \fR\fIX\fR

.fi
where
.I X
is separated from the
`\fB"\fP'
by a single
.SM SPACE
and consists of any combination of characters in the following list,
.B man
pipes its input to
.BR troff (1)
or
.BR nroff (1)
through the corresponding preprocessors.
.nf

     \fBe\fP     \fBeqn\fP(1), or \fBneqn\fP for \fBnroff\fP
     \fBr\fP     \fBrefer\fP(1)
     \fBt\fP     \fBtbl\fP(1)
     \fBv\fP     \fBvgrind\fP(1)

.fi
.LP
If
.B eqn
or
.B neqn
is invoked,
it will automatically read the file
.B /usr/pub/eqnchar
(see
.BR eqnchar (7)).
If
.BR nroff (1)
is invoked,
.BR col (1V)
is automatically used.
.SH "COMPRESSED MANUAL PAGES"
.B man
allows its manual pages to be compressed by either
.BR compress ,
.BR freeze ,
or
.BR gzip ,
in which case the manual page must have the suffix
.BR .Z ,
.BR .F ,
or
.BR .gz ,
respectively.  Note that the test for these suffixes is case sensitive
and if the incorrect case is used then the compressed file will be passed
to
.B nroff
with unpredictable results.
.LP
Compression may be used on files in either (or both) of the
.BR man? " and " cat?
subdirectories.  Do not compress
.BR aroff (1)
source files since compressed files in the
.BR man?
subdirectory are always assumed to be
.BR nroff (1)
source.
.SH ENVIRONMENT
.IP \fBMANPATH\fP
If set,
its value overrides
.B /usr/man
as the default search path.
(The
.B \-M
flag, in turn, overrides this value.)
See the description of the
.B \-M
flag for syntax details.
.IP \fBUSRMAN\fP
If
.B MANPATH
is not set, then the value of
.B USRMAN
(if set) overrides
.B /usr/man
as the default search path.
(The
.B \-M
flag, in turn, overrides this value.)
See the description of the
.B \-M
flag for syntax details.
.IP \fBMANDIR\fP
If neither
.B MANPATH
nor
.B USRMAN
is set, then the value of
.B MANDIR
(if set) overrides
.B /usr/man
as the default search path.
(The
.B \-M
flag, in turn, overrides this value.)
See the description of the
.B \-M
flag for syntax details.
.IP \fBPAGER\fP
A program to use for interactively delivering
.BR man 's
output to the screen.
If not set,
.RB ` "/bin/more" '
(see
.BR more (1))
is used.
.IP \fBTCAT\fP
The name of the program to use to display
.BR troff ed
manual pages.
If not set,
.RB ` "lpr \-t" '
(see
.BR lpr (1))
is used.
.IP \fBTROFF\fP
The name of the formatter to use when the
.B \-t
flag is given.
If not set,
.RB ` "troff \-t" '
is used.
.SH FILES
.B /usr/[share]/man
.RS
root of the standard manual page directory subtree
.RE
.sp
.B /usr/[share]/man/man?/*
.RS
unformatted manual entries
.RE
.sp
.B /usr/[share]/man/cat?/*
.RS
.BR nroff ed
manual entries
.RE
.sp
.B /usr/[share]/man/fmt?/*
.RS
.BR troff ed
manual entries
.RE
.sp
.B /usr/[share]/man/whatis
.RS
table of contents and keyword database
.RE
.sp
.B /usr/[share]/lib/tmac/tmac.an
.RS
standard
.B \-man
macro package
.RE
.sp
.B /usr/pub/eqnchar
.SH "SEE ALSO"
.BR apropos (1),
.BR aroff (1),
.BR cat (1V),
.BR col (1V),
.BR compress (1),
.BR eqn (1),
.BR freeze (1),
.BR gzip (1),
.BR less (1),
.BR lpr (1),
.BR more (1),
.BR nroff (1),
.BR refer (1),
.BR tbl (1),
.BR troff (1),
.BR vgrind (1),
.BR vtroff (1),
.BR whatis (1),
.BR whereis (1),
.BR eqnchar (7),
.BR man (7),
.BR catman (8)
.br
.ne 5
.SH NOTES
.LP
Because
.B troff
is not 8-bit clean,
.B man
has not been made 8-bit clean.
.LP
The
.B \-f
and 
.B \-k
options use the
.B whatis
database, which is created by
.BR makewhatis (8).
.br
.ne 4
.LP
Although this version of
.B man
allows
.BR USRMAN " and " MANDIR
to be each a colon- or space-separated list of pathnames, other versions
of
.B man
treat the values of these environment variables as a single pathname.
For compatibility reasons, the use of these two environment variables
is discouraged; use
.B MANPATH
instead.
.SH BUGS
.LP
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.
.LP
Some dumb terminals cannot process the vertical motions produced
by the
.B e
.RB ( eqn (1))
preprocessing flag.
To prevent garbled output on these terminals,
when you use
.B e
also use
.BR t ,
to invoke
.BR col (1V)
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
.BR eqn (1)
output.
.LP
The code which calls the
.BR eqn (1),
.BR refer (1),
.BR tbl (1),
and
.BR vgrind (1)
preprocessors is not yet implemented.  Since these preprocessors do
not as yet exist for GNO, this is not too much of a problem.
.LP
Please report any other bugs to Devin Reade, <gdr@trenco.gno.org>.
.SH HISTORY
The GNO version of
.BR man
first appeared in GNO version 1.0 and was written by Mike Horwath.
This version was rewritten from scratch by Devin Reade.