5025 import and use mandoc
Reviewed by: Hans Rosenfeld <hans.rosenfeld@nexenta.com>
Reviewed by: Igor Kozhukhov <ikozhukhov@gmail.com>
Reviewed by: Robert Mustacchi <rm@joyent.com>
Reviewed by: Albert Lee <trisk@nexenta.com>
Approved by: TBD

*** 1,664 ****
! '\" te
  .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
! .\" Copyright (c) 1980 Regents of the University of California. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
! .TH MAN 1 "May 8, 2008"
! .SH NAME
! man \- find and display reference manual pages
! .SH SYNOPSIS
! .LP
! .nf
! \fBman\fR [\fB-\fR] [\fB-adFlrt\fR] [\fB-M\fR \fIpath\fR] [\fB-T\fR \fImacro-package\fR] [\fB-s\fR \fIsection\fR] \fIname\fR...
! .fi
! 
! .LP
! .nf
! \fBman\fR [\fB-M\fR \fIpath\fR] \fB-k\fR \fIkeyword\fR...
! .fi
! 
! .LP
! .nf
! \fBman\fR [\fB-M\fR \fIpath\fR] \fB-f\fR \fIfile\fR...
! .fi
! 
! .SH DESCRIPTION
! .sp
! .LP
! The \fBman\fR command displays information from the reference manuals. It
! displays complete manual pages that you select by \fIname\fR, or one-line
! summaries selected either by \fIkeyword\fR (\fB-k\fR), or by the name of an
! associated file (\fB-f\fR). If no manual page is located, \fBman\fR prints an
! error message.
! .SS "Source Format"
! .sp
! .LP
! Reference Manual pages are marked up with either \fBnroff\fR (see
! \fBnroff\fR(1)) or \fBSGML\fR (Standard Generalized Markup Language) tags (see
! \fBsgml\fR(5)). The \fBman\fR command recognizes the type of markup and
! processes the file accordingly. The various source files are kept in separate
! directories depending on the type of markup.
! .SS "Location of Manual Pages"
! .sp
! .LP
  The online Reference Manual page directories are conventionally located in
! \fB/usr/share/man\fR. The nroff sources are located in the
! \fB/usr/share/man/man\fR* directories. The \fBSGML\fR sources are located in
! the \fB/usr/share/man/sman\fR* directories. Each directory corresponds to a
  section of the manual. Since these directories are optionally installed, they
! might not reside on your host. You might have to mount \fB/usr/share/man\fR
  from a host on which they do reside.
! .sp
! .LP
! If there are preformatted, up-to-date versions in the corresponding \fBcat\fR*
! or \fBfmt\fR* directories, \fBman\fR simply displays or prints those versions.
! If the preformatted version of interest is out of date or missing, \fBman\fR
! reformats it prior to display and stores the preformatted version if \fBcat\fR*
! or \fBfmt\fR* is writable. The \fBwindex\fR database is not updated. See
! \fBcatman\fR(1M). If directories for the preformatted versions are not
! provided, \fBman\fR reformats a page whenever it is requested. \fBman\fR uses a
! temporary file to store the formatted text during display.
! .sp
! .LP
! If the standard output is not a terminal, or if the `\fB-\fR' flag is given,
! \fBman\fR pipes its output through \fBcat\fR(1). Otherwise, \fBman\fR pipes its
! output through \fBmore\fR(1) to handle paging and underlining on the screen.
! .SH OPTIONS
! .sp
! .LP
  The following options are supported:
! .sp
! .ne 2
! .na
! \fB\fB-a\fR\fR
! .ad
! .RS 20n
! Shows all manual pages matching \fIname\fR within the \fBMANPATH\fR search
! path. Manual pages are displayed in the order found.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-d\fR\fR
! .ad
! .RS 20n
  Debugs. Displays what a section-specifier evaluates to, method used for
! searching, and paths searched by \fBman\fR.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-f\fR \fIfile ...\fR\fR
! .ad
! .RS 20n
! \fBman\fR attempts to locate manual pages related to any of the given
! \fIfile\fRs. It strips the leading path name components from each \fIfile\fR,
  and then prints one-line summaries containing the resulting basename or names.
! This option also uses the \fBwindex\fR database.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-F\fR\fR
! .ad
! .RS 20n
! Forces \fBman\fR to search all directories specified by \fBMANPATH\fR or the
! \fBman.cf\fR file, rather than using the \fBwindex\fR lookup database. This
! option is useful if the database is not up to date and it has been made the
! default behavior of the \fBman\fR command. The option therefore does not have
! to be invoked and is documented here for reference only.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-k\fR \fIkeyword ...\fR\fR
! .ad
! .RS 20n
! Prints out one-line summaries from the \fBwindex\fR database (table of
! contents) that contain any of the given \fIkeyword\fRs. The \fBwindex\fR
! database is created using \fBcatman\fR(1M).
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-l\fR\fR
! .ad
! .RS 20n
! Lists all manual pages found matching \fIname\fR within the search path.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-M\fR \fIpath\fR\fR
! .ad
! .RS 20n
! Specifies an alternate search path for manual pages. \fIpath\fR is a
! colon-separated list of directories that contain manual page directory
! subtrees. For example, if \fIpath\fR is \fB/usr/share/man:/usr/local/man\fR,
! \fBman\fR searches for \fIname\fR in the standard location, and then
! \fB/usr/local/man\fR. When used with the \fB-k\fR or \fB-f\fR options, the
! \fB-M\fR option must appear first. Each directory in the \fIpath\fR is assumed
! to contain subdirectories of the form \fBman\fR* or \fBsman\fR* , one for each
! section. This option overrides the \fBMANPATH\fR environment variable.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-r\fR\fR
! .ad
! .RS 20n
! Reformats the manual page, but does not display it. This replaces the \fBman\fR
! \fB-\fR \fB-t\fR \fIname\fR combination.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-s\fR \fIsection ...\fR\fR
! .ad
! .RS 20n
! Specifies sections of the manual for \fBman\fR to search. The directories
! searched for \fIname\fR are limited to those specified by \fIsection\fR.
! \fIsection\fR can be a numerical digit, perhaps followed by one or more letters
! to match the desired section of the manual, for example, "\fB3libucb\fR". Also,
! \fIsection\fR can be a word, for example, \fBlocal\fR, \fBnew\fR, \fBold\fR,
! \fBpublic\fR. \fIsection\fR can also be a letter. To specify multiple sections,
! separate each section with a comma. This option overrides the \fBMANPATH\fR
! environment variable and the \fBman.cf\fR file. See \fBSearch\fR \fBPath\fR
! below for an explanation of how \fBman\fR conducts its search.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-t\fR\fR
! .ad
! .RS 20n
! \fBman\fR arranges for the specified manual pages to be \fBtroff\fRed to a
! suitable raster output device (see \fBtroff\fR(1)). If both the \fB-\fR and
! \fB-t\fR flags are given, \fBman\fR updates the \fBtroff\fRed versions of each
! named \fIname\fR (if necessary), but does not display them.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB-T\fR \fImacro-package\fR\fR
! .ad
! .RS 20n
! Formats manual pages using \fImacro-package\fR rather than the standard
! \fB-man\fR macros defined in \fB/usr/share/lib/tmac/an\fR. See \fBSearch
! Path\fR under USAGE for a complete explanation of the default search path
! order.
! .RE
! 
! .SH OPERANDS
! .sp
! .LP
  The following operand is supported:
! .sp
! .ne 2
! .na
! \fB\fIname\fR\fR
! .ad
! .RS 8n
  The name of a standard utility or a keyword.
! .RE
! 
! .SH USAGE
! .sp
! .LP
! The usage of \fBman\fR is described below:
! .SS "Manual Page Sections"
! .sp
! .LP
! Entries in the reference manuals are organized into \fIsection\fRs. A section
  name consists of a major section name, typically a single digit, optionally
  followed by a subsection name, typically one or more letters. An unadorned
! major section name, for example, "\fB9\fR", does not act as an abbreviation for
! the subsections of that name, such as "\fB9e\fR", "\fB9f\fR", or "\fB9s\fR".
! That is, each subsection must be searched separately by \fBman\fR \fB-s\fR.
  Each section contains descriptions apropos to a particular reference category,
! with subsections refining these distinctions. See the \fBintro\fR manual pages
! for an explanation of the classification used in this release.
! .SS "Search Path"
! .sp
! .LP
! Before searching for a given \fIname\fR, \fBman\fR constructs a list of
! candidate directories and sections. \fBman\fR searches for \fIname\fR in the
! directories specified by the \fBMANPATH\fR environment variable.
! .sp
! .LP
! In the absence of \fBMANPATH\fR, \fBman\fR constructs its search path based
! upon the \fBPATH\fR environment variable, primarily by substituting \fBman\fR
! for the last component of the \fBPATH\fR element. Special provisions are added
! to account for unique characteristics of directories such as \fB/sbin\fR,
! \fB/usr/ucb\fR, \fB/usr/xpg4/bin\fR, and others. If the file argument contains
! a \fB/\fR character, the \fIdirname\fR portion of the argument is used in place
! of \fBPATH\fR elements to construct the search path.
! .sp
! .LP
! Within the manual page directories, \fBman\fR confines its search to the
  sections specified in the following order:
! .RS +4
! .TP
! .ie t \(bu
! .el o
! \fIsection\fRs specified on the command line with the \fB-s\fR option
! .RE
! .RS +4
! .TP
! .ie t \(bu
! .el o
! \fIsection\fRs embedded in the \fBMANPATH\fR environment variable
! .RE
! .RS +4
! .TP
! .ie t \(bu
! .el o
! \fIsection\fRs specified in the \fBman.cf\fR file for each directory specified
! in the \fBMANPATH\fR environment variable
! .RE
! .sp
! .LP
! If none of the above exist, \fBman\fR searches each directory in the manual
  page path, and displays the first matching manual page found.
! .sp
! .LP
! The \fBman.cf\fR file has the following format:
! .sp
! .in +2
! .nf
! MANSECTS=\fIsection\fR[,\fIsection\fR]...
! .fi
! .in -2
! .sp
! 
! .sp
! .LP
! Lines beginning with `\fB#\fR' and blank lines are considered comments, and are
! ignored. Each directory specified in \fBMANPATH\fR can contain a manual page
  configuration file, specifying the default search order for that directory.
! .SH FORMATTING MANUAL PAGES
! .sp
! .LP
! Manual pages are marked up in \fBnroff\fR(1) or \fBsgml\fR(5). Nroff manual
! pages are processed by \fBnroff\fR(1) or \fBtroff\fR(1) with the \fB-man\fR
! macro package. Please refer to \fBman\fR(5) for information on macro usage.
! \fBSGML\fR\(emtagged manual pages are processed by an \fBSGML\fR parser and
! passed to the formatter.
! .SS "Preprocessing Nroff Manual Pages"
! .sp
! .LP
! When formatting an nroff manual page, \fBman\fR examines the first line to
! determine whether it requires special processing. If the first line is a string
! of the form:
! .sp
! .in +2
! .nf
! \&'\e" \fIX\fR
! .fi
! .in -2
! .sp
! 
! .sp
! .LP
! where \fIX\fR is separated from the `\fB"\fR' by a single SPACE and consists of
! any combination of characters in the following list, \fBman\fR pipes its input
! to \fBtroff\fR(1) or \fBnroff\fR(1) through the corresponding preprocessors.
! .sp
! .ne 2
! .na
! \fB\fBe\fR\fR
! .ad
! .RS 5n
! \fBeqn\fR(1), or \fBneqn\fR for \fBnroff\fR
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBr\fR\fR
! .ad
! .RS 5n
! \fBrefer\fR(1)
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBt\fR\fR
! .ad
! .RS 5n
! \fBtbl\fR(1)
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBv\fR\fR
! .ad
! .RS 5n
! \fBvgrind\fR(1)
! .RE
! 
! .sp
! .LP
! If \fBeqn\fR or \fBneqn\fR is invoked, it automatically reads the file
! \fB/usr/pub/eqnchar\fR (see \fBeqnchar\fR(5)). If \fBnroff\fR(1) is invoked,
! \fBcol\fR(1) is automatically used.
! .SS "Referring to Other nroff Manual Pages"
! .sp
! .LP
! If the first line of the nroff manual page is a reference to another manual
  page entry fitting the pattern:
! .sp
! .in +2
! .nf
! \&.so man*/\fIsourcefile\fR
! .fi
! .in -2
! .sp
! 
! .sp
! .LP
! \fBman\fR processes the indicated file in place of the current one. The
  reference must be expressed as a path name relative to the root of the manual
  page directory subtree.
! .sp
! .LP
  When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
  ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
  manner.
! .SS "Processing SGML Manual Pages"
! .sp
! .LP
! Manual pages are identified as being marked up in SGML by the presence of the
! string \fB<!DOCTYPE\fR\&. If the file also contains the string
! \fBSHADOW_PAGE\fR, the file refers to another manual page for the content. The
! reference is made with a file entity reference to the manual page that contains
! the text. This is similar to the \fB\&.so\fR mechanism used in the nroff
! formatted man pages.
! .SH ENVIRONMENT VARIABLES
! .sp
! .LP
! See \fBenviron\fR(5) for descriptions of the following environment variables
! that affect the execution of \fBman\fR: \fBLANG\fR, \fBLC_ALL\fR,
! \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
! .sp
! .ne 2
! .na
! \fB\fBMANPATH\fR\fR
! .ad
! .RS 11n
  A colon-separated list of directories; each directory can be followed by a
  comma-separated list of sections. If set, its value overrides
  \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
  file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
  turn, override these values.)
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBPAGER\fR\fR
! .ad
! .RS 11n
! A program to use for interactively delivering \fBman\fR's output to the screen.
! If not set, `\fBmore\fR \fB-s\fR' is used. See \fBmore\fR(1).
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBTCAT\fR\fR
! .ad
! .RS 11n
! The name of the program to use to display \fBtroff\fRed manual pages.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBTROFF\fR\fR
! .ad
! .RS 11n
! The name of the formatter to use when the \fB-t\fR flag is given. If not set,
! \fBtroff\fR(1) is used.
! .RE
! 
! .SH EXAMPLES
! .LP
! \fBExample 1 \fRCreating a PostScript Version of a man page
! .sp
! .LP
! The following example creates the \fBpipe\fR(2) man page in postscript for csh,
! tcsh, ksh and sh users:
! 
! .sp
! .in +2
! .nf
!         % env TCAT=/usr/lib/lp/postscript/dpost man -t -s 2 pipe > pipe.ps
! .fi
! .in -2
! .sp
! 
! .sp
! .LP
! This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
! the default printer, if the user wants a postscript file version of the man
! page.
! 
! .LP
! \fBExample 2 \fRCreating a Text Version of a man page
! .sp
! .LP
! The following example creates the \fBpipe\fR(2) man page in ascii text:
! 
! .sp
! .in +2
! .nf
! man pipe.2 | col -x -b > pipe.text
! .fi
! .in -2
! .sp
! 
! .sp
! .LP
! This is an alternative to using \fBman\fR \fB-t\fR, which sends the man page to
! the default printer, if the user wants a text file version of the man page.
! 
! .SH EXIT STATUS
! .sp
! .LP
! The following exit values are returned:
! .sp
! .ne 2
! .na
! \fB\fB0\fR\fR
! .ad
! .RS 6n
! Successful completion.
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB>0\fR\fR
! .ad
! .RS 6n
! An error occurred.
! .RE
! 
! .SH FILES
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man\fR\fR
! .ad
! .sp .6
! .RS 4n
  Root of the standard manual page directory subtree
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man/man?/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! Unformatted nroff manual entries
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man/sman?/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! Unformatted \fBSGML\fR manual entries
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man/cat?/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! \fBnroff\fRed manual entries
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man/fmt?/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! \fBtroff\fRed manual entries
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/man/windex\fR\fR
! .ad
! .sp .6
! .RS 4n
  Table of contents and keyword database
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/lib/tmac/an\fR\fR
! .ad
! .sp .6
! .RS 4n
! Standard \fB-man\fR macro package
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/lib/sgml/locale/C/dtd/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! \fBSGML\fR document type definition files
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/lib/sgml/locale/C/solbook/*\fR\fR
! .ad
! .sp .6
! .RS 4n
! \fBSGML\fR style sheet and entity definitions directories
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fB/usr/share/lib/pub/eqnchar\fR\fR
! .ad
! .sp .6
! .RS 4n
! Standard definitions for \fBeqn\fR and \fBneqn\fR
! .RE
! 
! .sp
! .ne 2
! .na
! \fB\fBman.cf\fR\fR
! .ad
! .sp .6
! .RS 4n
  Default search order by section
! .RE
! 
! .SH ATTRIBUTES
! .sp
! .LP
! See \fBattributes\fR(5) for descriptions of the following attributes:
! .sp
! 
! .sp
! .TS
! box;
! c | c
! l | l .
! ATTRIBUTE TYPE  ATTRIBUTE VALUE
! _
! CSI     Enabled, see \fBNOTES\fR.
! _
! Interface Stability     Committed
! _
! Standard        See \fBstandards\fR(5).
! .TE
! 
! .SH SEE ALSO
! .sp
! .LP
! \fBapropos\fR(1), \fBcat\fR(1), \fBcol\fR(1), \fBdpost\fR(1), \fBeqn\fR(1),
! \fBmore\fR(1), \fBnroff\fR(1), \fBrefer\fR(1), \fBtbl\fR(1), \fBtroff\fR(1),
! \fBvgrind\fR(1), \fBwhatis\fR(1), \fBcatman\fR(1M), \fBattributes\fR(5),
! \fBenviron\fR(5), \fBeqnchar\fR(5), \fBman\fR(5), \fBsgml\fR(5),
! \fBstandards\fR(5)
! .SH NOTES
! .sp
! .LP
! The \fB-f\fR and \fB-k\fR options use the \fBwindex\fR database, which is
! created by \fBcatman\fR(1M).
! .sp
! .LP
! The \fBman\fR command is CSI-capable. However, some utilities invoked by the
! \fBman\fR command, namely, \fBtroff\fR, \fBeqn\fR, \fBneqn\fR, \fBrefer\fR,
! \fBtbl\fR, and \fBvgrind\fR, are not verified to be CSI-capable. Because of
! this, the man command with the \fB-t\fR option can not handle non-EUC data.
! Also, using the \fBman\fR command to display man pages that require special
! processing through \fBeqn\fR, \fBneqn\fR, \fBrefer\fR, \fBtbl\fR, or
! \fBvgrind\fR can not be CSI-capable.
! .SH BUGS
! .sp
! .LP
  The manual is supposed to be reproducible either on a phototypesetter or on an
! \fBASCII\fR terminal. However, on a terminal some information (indicated by
  font changes, for instance) is lost.
- .sp
- .LP
- Some dumb terminals cannot process the vertical motions produced by the \fBe\fR
- (see \fBeqn\fR(1)) preprocessing flag. To prevent garbled output on these
- terminals, when you use \fBe\fR, also use \fBt\fR, to invoke \fBcol\fR(1)
- implicitly. This workaround has the disadvantage of eliminating superscripts
- and subscripts, even on those terminals that can display them. Control-q clears
- a terminal that gets confused by \fBeqn\fR(1) output.
--- 1,401 ----
! .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
! .\" Copyright (c) 1980 Regents of the University of California.
! .\" The Berkeley software License Agreement specifies the terms and conditions
! .\" for redistribution.
! .Dd Jul 18, 2014
! .Dt MAN 1
! .Os
! .Sh NAME
! .Nm man
! .Nd find and display reference manual pages
! .Sh SYNOPSIS
! .Nm
! .Op Fl
! .Op Fl adFlrt
! .Op Fl T Ar macro-package
! .Op Fl M Ar path
! .Op Fl s Ar section
! .Ar name ...
! .Nm
! .Op Fl M Ar path
! .Op Fl s Ar section
! .Fl k
! .Ar keyword
! .Ar ...
! .Nm
! .Op Fl M Ar path
! .Op Fl s Ar section
! .Fl f
! .Ar
! .Nm
! .Op Fl M Ar path
! .Fl w
! .Sh DESCRIPTION
! The
! .Nm
! command displays information from the reference manuals. It
! displays complete manual pages that you select by
! .Ar name ,
! or one-line summaries selected either by
! .Ar keyword
! .Pq Fl k ,
! or by the name of an associated file
! .Pq Fl f .
! If no manual page is located,
! .Nm
! prints an error message.
! .Ss "Source Format"
! Reference Manual pages are marked up with either
! .Xr man 5 ,
! or
! .Xr mdoc 5
! language tags. The
! .Nm
! command recognizes the type of markup and
! processes the file accordingly.
! .
! .Ss "Location of Manual Pages"
! .
  The online Reference Manual page directories are conventionally located in
! .Pa /usr/share/man .
! Each directory corresponds to a
  section of the manual. Since these directories are optionally installed, they
! might not reside on your host. You might have to mount
! .Pa /usr/share/man
  from a host on which they do reside.
! The
! .Nm
! command reformats a page whenever it is requested.
! .Pp
! If the standard output is not a terminal, or if the
! .Fl
! flag is given,
! .Nm
! pipes its output through
! .Xr cat 1 .
! Otherwise,
! .Nm
! pipes its output through a pager such as
! .Xr more 1
! to handle paging and underlining on the screen.
! .Sh OPTIONS
  The following options are supported:
! .Bl -tag -width indent
! .It Fl a
! Shows all manual pages matching
! .Ar name
! within the
! .Ev MANPATH
! search path. Manual pages are displayed in the order found.
! .It Fl d
  Debugs. Displays what a section-specifier evaluates to, method used for
! searching, and paths searched by
! .Nm .
! .It Fl f Ar file ...
! Attempts to locate manual pages related to any of the given
! .Ar file
! names. It strips the leading path name components from each
! .Ar file ,
  and then prints one-line summaries containing the resulting basename or names.
! This option also uses the
! .Pa whatis
! database.
! .It Fl F
! This option is present for backwards compatibility and is documented
! here for reference only.  It performs no function.
! .It Fl k Ar keyword ...
! Prints out one-line summaries from the
! .Pa whatis
! database (table of contents) that contain any of the given
! .Ar keyword .
! The
! .Pa whatis
! database is created using the
! .Fl w
! option.
! .It Fl l
! Lists all manual pages found matching
! .Ar name
! within the search path.
! .It Fl M Ar path
! Specifies an alternate search path for manual pages. The
! .Ar path
! is a colon-separated list of directories that contain manual page directory
! subtrees. For example, if
! .Ar path
! is
! .Pa /usr/share/man:/usr/local/man ,
! .Nm
! searches for
! .Ar name
! in the standard location, and then
! .Pa /usr/local/man .
! When used with the
! .Fl k ,
! .Fl f ,
! or
! .Fl w
! options, the
! .Fl M
! option must appear first. Each directory in the
! .Ar path
! is assumed to contain subdirectories of the form
! .Pa man* ,
! one for each section. This option overrides the
! .Ev MANPATH
! environment variable.
! .It Fl r
! Reformats the manual page, checking for formatting errors, but does not
! display it.
! .It Fl s Ar section
! Specifies sections of the manual for
! .Nm
! to search. The directories searched for
! .Ar name
! are limited to those specified by
! .Ar section .
! .Ar section
! can be a numerical digit, perhaps followed by one or more letters
! to match the desired section of the manual, for example,
! .Li "3libucb".
! Also,
! .Ar section
! can be a word, for example,
! .Li local ,
! .Li new ,
! .Li old ,
! .Li public .
! .Ar section
! can also be a letter. To specify multiple sections,
! separate each section with a comma. This option overrides the
! .Ev MANPATH
! environment variable and the
! .Pa man.cf
! file. See
! .Sx Search Path
! below for an explanation of how
! .Nm
! conducts its search.
! .It Fl t
! Arranges for the specified manual pages to be sent to the default
! printer as PostScript.
! .It Fl T Ar macro-package
! This option is present for backwards compatibility and is documented
! here for reference only.  It performs no function.
! .It Fl w
! Updates the
! .Nm whatis
! database.
! .El
! .Sh OPERANDS
  The following operand is supported:
! .Bl -tag -width indent
! .It Ar name
  The name of a standard utility or a keyword.
! .El
! .Sh USAGE
! The usage of
! .Nm
! is described below:
! .
! .Ss "Manual Page Sections"
! .
! Entries in the reference manuals are organized into
! .Em sections .
! A section
  name consists of a major section name, typically a single digit, optionally
  followed by a subsection name, typically one or more letters. An unadorned
! major section name, for example,
! .Qq 9 ,
! does not act as an abbreviation for
! the subsections of that name, such as
! .Qq 9e ,
! .Qq 9f ,
! or
! .Qq 9s .
! That is, each subsection must be searched separately by
! .Nm
! .Fl s .
  Each section contains descriptions apropos to a particular reference category,
! with subsections refining these distinctions. See the
! .Em intro
! manual pages for an explanation of the classification used in this release.
! .
! .Ss "Search Path"
! .
! Before searching for a given
! .Ar name ,
! .Nm
! constructs a list of candidate directories and sections.
! It searches for
! .Ar name
! in the directories specified by the
! .Ev MANPATH
! environment variable.
! .Lp
! In the absence of
! .Ev MANPATH ,
! .Nm
! constructs its search path based upon the
! .Ev PATH
! environment variable, primarily by substituting
! .Li man
! for the last component of the
! .Ev PATH
! element. Special provisions are added
! to account for unique characteristics of directories such as
! .Pa /sbin ,
! .Pa /usr/ucb ,
! .Pa /usr/xpg4/bin ,
! and others. If the file argument contains
! a
! .Qq /
! character, the
! .Em dirname
! portion of the argument is used in place of
! .Ev PATH
! elements to construct the search path.
! .Lp
! Within the manual page directories,
! .Nm
! confines its search to the
  sections specified in the following order:
! .Bl -bullet
! .It
! .Ar sections
! specified on the command line with the
! .Fl s
! option
! .It
! .Ar sections
! embedded in the
! .Ev MANPATH
! environment variable
! .It
! .Ar sections
! specified in the
! .Pa man.cf
! file for each directory specified in the
! .Ev MANPATH
! environment variable
! .El
! If none of the above exist,
! .Nm
! searches each directory in the manual
  page path, and displays the first matching manual page found.
! .Lp
! The
! .Pa man.cf
! file has the following format:
! .Lp
! .Dl Pf MANSECTS= Ar section , Ns Op Ar section...
! .Lp
! Lines beginning with
! .Sq Li #
! and blank lines are considered comments, and are
! ignored. Each directory specified in
! .Ev MANPATH
! can contain a manual page
  configuration file, specifying the default search order for that directory.
! .Sh "Referring to Other Manual Pages"
! If the first line of the manual page is a reference to another manual
  page entry fitting the pattern:
! .Lp
! .Dl \&.so man*/\fIsourcefile\fR
! .Lp
! .Nm
! processes the indicated file in place of the current one. The
  reference must be expressed as a path name relative to the root of the manual
  page directory subtree.
! .Lp
  When the second or any subsequent line starts with \fB\&.so\fR, \fBman\fR
  ignores it; \fBtroff\fR(1) or \fBnroff\fR(1) processes the request in the usual
  manner.
! .Sh ENVIRONMENT VARIABLES
! See
! .Xr environ 5
! for descriptions of the following environment variables
! that affect the execution of
! .Nm man :
! .Ev LANG ,
! .Ev LC_ALL ,
! .Ev LC_CTYPE ,
! .Ev LC_MESSAGES ,
! and
! .Ev NLSPATH .
! .Bl -tag -width indent
! .It Ev MANPATH
  A colon-separated list of directories; each directory can be followed by a
  comma-separated list of sections. If set, its value overrides
  \fB/usr/share/man\fR as the default directory search path, and the \fBman.cf\fR
  file as the default section search path. The \fB-M\fR and \fB-s\fR flags, in
  turn, override these values.)
! .It Ev PAGER
! A program to use for interactively delivering
! output to the screen. If not set,
! .Sq Nm more Fl s
! is used. See
! .Xr more 1 .
! .El
! .Sh FILES
! .Bl -tag -width indent
! .It Pa /usr/share/man
  Root of the standard manual page directory subtree
! .It Pa /usr/share/man/man?/*
! Unformatted manual entries
! .It Pa /usr/share/man/whatis
  Table of contents and keyword database
! .It Pa man.cf
  Default search order by section
! .El
! .Sh EXIT STATUS
! .Ex -std man
! .Sh EXAMPLES
! .
! .Ss Example 1: Creating a PostScript Version of a man page
! .
! The following example spools the
! .Xr pipe 2
! man page in PostScript to the default printer:
! .Pp
! .Dl % man -t -s 2 pipe
! .Pp
! Note that
! .Xr mandoc 1
! can be used to obtain the PostScript content directly.
! .Ss Example 2: Creating a Text Version of a man page
! The following example creates the
! .Xr pipe 2
! man page in ASCII text:
! .Pp
! .Dl % man pipe.2 | col -x -b > pipe.text
! .Sh CODE SET INDEPENDENCE
! Enabled.
! .Sh INTERFACE STABILITY
! .Nm Committed .
! .Sh SEE ALSO
! .Xr apropos 1 ,
! .Xr cat 1 ,
! .Xr col 1 ,
! .Xr mandoc 1 ,
! .Xr more 1 ,
! .Xr whatis 1 ,
! .Xr environ 5 ,
! .Xr man 5 ,
! .Xr mdoc 5
! .Sh NOTES
! The
! .Fl f
! and
! .Fl k
! options use the
! .Nm whatis
! database, which is
! created with the
! .Fl w
! option.
! .Sh BUGS
  The manual is supposed to be reproducible either on a phototypesetter or on an
! ASCII terminal. However, on a terminal some information (indicated by
  font changes, for instance) is lost.