mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-06-04 10:29:30 +00:00
73ce022151
original makewhatis repository. Earlier versions of man, apropos, and whatis were by other authors (these are written from scratch). Catman is new.
520 lines
10 KiB
Groff
520 lines
10 KiB
Groff
.\" 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
|
|
.\" by Devin Reade <gdr@myrias.com>. All rights reserved.
|
|
.\"
|
|
.TH MAN 1 "Commands and Applications" "24 July 95" "Version 3.0"
|
|
.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
|
|
.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@myrias.com>.
|
|
.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.
|