Xref: utzoo comp.lang.perl:3474 alt.sources:2968
Path: utzoo!utgpu!cs.utexas.edu!samsung!uunet!convex!usenet
From: tchrist@convex.COM (Tom Christiansen)
Newsgroups: comp.lang.perl,alt.sources
Subject: The Answer to All Man's Problems (part 1 of 6)
Keywords: man perl
Message-ID: <1991Jan07.221440.9887@convex.com>
Date: 7 Jan 91 22:14:40 GMT
References: <1991Jan07.220902.9726@convex.com>
Sender: usenet@convex.com (news access account)
Reply-To: tchrist@convex.COM (Tom Christiansen)
Followup-To: alt.sources.d
Organization: CONVEX Software Development, Richardson, TX
Lines: 1000
Nntp-Posting-Host: pixel.convex.com

#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create:
#	man
# This archive created: Mon Jan  7 15:58:51 1991
export PATH; PATH=/bin:/usr/bin:$PATH
if test ! -d 'man'
then
	echo shar: "creating directory 'man'"
	mkdir 'man'
fi
echo shar: "entering directory 'man'"
cd 'man'
echo shar: "extracting 'makewhatis.8'" '(9442 characters)'
if test -f 'makewhatis.8'
then
	echo shar: "will not over-write existing file 'makewhatis.8'"
else
sed 's/^	X//' << \SHAR_EOF > 'makewhatis.8'
	X.TH MAKEWHATIS 8
	X.CX		\" probably only makes sense on Convex machines
	X.\"
	X.de SB		\" small and bold
	X.if !"\\$1"" \\s-1\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
	X..
	X.\"
	X.de T		\" switch to typewriter font
	X.ft TA		\" probably want CW if you don't have TA font
	X..
	X.\"
	X.de TY		\" put $1 in typewriter font
	X.if t .T
	X.if n ``\c
	X\\$1\c
	X.if t .ft P
	X.if n \&''\c
	X\\$2
	X..
	X.\"
	X.de M		\" man page reference
	X\\fI\\$1\\fR\\|(\\$2\)\\$3
	X..
	X.SH NAME
	Xmakewhatis \- rebuild the whatis database
	X.SH SYNOPSIS
	X.B /usr/lib/makewhatis 
	X[
	X.B \-v
	X] [
	X.B \-n
	X] [
	X.B \-y
	X] [[
	X.B \-M
	X] manpath ]
	X.SH DESCRIPTION
	XThe
	X.I makewhatis
	Xprogram
	Xrebuilds the text and 
	X.M dbm 3X
	Xforms of the 
	X.I whatis
	Xdatabase 
	Xfrom the on-line manual pages for a given
	X\fImanpath\fP, or from 
	X.I /usr/man
	Xif none is supplied.
	XThese files are 
	Xused by the
	X.M man 1 , 
	X.M whatis 1 , 
	Xand 
	X.M apropos 1
	Xprograms to locate man pages and to print out the one-line 
	Xdescriptions given by 
	X.I whatis
	Xand 
	X.I apropos\c
	X\&.
	XThe
	X.I makewhatis
	Xprogram
	Xshould be run whenever new man pages are added so these programs can 
	Xfind them.  
	X.PP
	XEach component of the colon-delimited 
	X.I manpath 
	Xis interpreted to be the root
	Xof a new tree containing directories of the form \fIman*\fP,  
	Xwithin which are unformatted man pages of the form \fI*.*\fP.  A separate 
	X.I whatis
	Xfile and corresponding 
	X.I dbm 
	Xfiles, 
	X.I whatis.pag
	Xand 
	X\fIwhatis.dir\fP,
	Xwill be placed at the root of that man tree.
	XFiles or directories ending in tilde (\fB~\fP) or in \fB.bak\fP or \fB.old\fP (in either case)
	Xwill be skipped, as will a section named \fBman0\fP, should it exist. 
	X.PP
	XIn general, files in section \fBmanX\fP should end in \fB.X*\fP, where
	X\fBX\fP is a section of the manual like \fB1\fP or \fB3x11\fP.  This means
	Xit's ok to put things ending in \fB1c\fP in \fBman1\fP, but not things 
	Xending in \fB3s\fP.  Any man page whose name doesn't match these criteria
	Xwill generate a warning, but will be processed anyway.  The exception
	Xto this is the \fBmano\fP subdirectory, which has 
	Xtraditionally been the receptacle of all obsolete
	Xman pages irrespective of their file extension.  A better way to do that
	Xwould be to have an entire man tree dedicated to this, as in 
	X\fI/usr/old/man/\fP.
	X.PP
	XMultiple entries occurring in the 
	X.SB NAME
	Xsection or as links (hard, soft, or via \fB.so\fP inclusion) will all be
	Xstored under the same man page name.  This method can save significant amounts
	Xof disk space because it guarantees that only one cat page need be generated, 
	Xregardless of how many ways you can get at the corresponding man page.  
	XMaintaining aliases as links or via a one-line file that \fB.so\fP's the 
	Xreal man page (once the only way to do this) is still supported although
	Xno longer
	Xrequired; mere inclusion in the 
	X.SB NAME
	Xsection is sufficient.
	X.PP
	XEmbedded point and font changes will be removed from the output, and
	X\fItroff\fP string macros for hyphens and underscores will be 
	Xtranslated into their corresponding 
	X\s-1ASCII\s0
	Xrepresentations.  In 
	Xgeneral, all that can be done will be done to produce nicely readable output for
	X.M whatis 1 .
	X.PP
	XThe 
	X.B \-v
	Xflag will generate verbose output, reporting such things as each new man tree
	Xexamined, each subdirectory, each file that is opened, and each entry in the 
	X.SB NAME
	Xsection that is found and stored.  Simple tracing information is printed
	Xto the standard output, while to standard error are directed
	Xmore serious warnings.
	X.PP
	XThe 
	X.B \-n
	Xoption can be used to check whether the database needs rebuilding.  It 
	Xwill report on the first file in each man path that is out of date.  Note
	Xthat this is the only automated way to determine this; neither 
	X.I makewhatis
	Xnor 
	X.I man
	Xwill realize that the database is out of date, so you should be careful
	Xto rebuild it whenever new man pages are added.
	X.PP
	XThe
	X.B \-y
	Xoption is similar, but after finding something out of date, 
	X.I makewhatis
	Xwill automatically rebuild its database.
	X.PP
	XSupport for compressed man pages is provided in the following way:
	Xif the name of the subdirectory itself ends in \fB.Z\fP, as in \fBman8.Z\fP,
	Xthen all its files are assumed to have been compressed with 
	X.M compress 1L .
	XAlternatively, individual files ending in \fB.Z\fP are also 
	Xconsidered to be compressed.
	XCompressed files are processed with 
	X.M zcat 1L .  
	X.SH EXAMPLES
	X.ft TA
	X.nf 
	X.ta 3i
	X% makewhatis -y	# build /usr/man database only if out of date
	X% makewhatis /usr/local/man	# make local man page database
	X% makewhatis -v ~/man	# make personal man page database verbosely
	X% makewhatis -n $MANPATH	# tell if any dbase in $MANPATH out of date
	X.ft P
	X.fi
	X.SH FILES
	X.nf
	X.ta \w'/usr/man/whatis.pag  'u
	X\fI/usr/man/whatis\fP	default whatis database, text version
	X\fI/usr/man/whatis.pag\fP	\fIdbm\fP index file for default whatis database
	X\fI/usr/man/whatis.dir\fP	\fIdbm\fP data file for default whatis database
	X\fI/usr/man/man*/*.*\fR	default (unformatted) man pages
	X\fI/usr/man/cat*/*.*\fR	formatted man pages
	X.SH "SEE ALSO"
	Xman(1),
	Xwhatis(1),
	Xapropos(1),
	Xperl(1),
	Xcompress(1L),
	Xdbm(3X),
	Xman(7),
	Xcatman(8)
	X.SH DIAGNOSTICS
	XNumerous diagnostics may be issued, especially if the 
	X.B \-v
	Xflag has been given.  Here are messages that may require
	Xfurther attention.  The 
	X.B %s 
	Xand 
	X.B %d
	Xfields
	Xin the descriptions indicate strings and integers respectively
	Xthat will be filled
	Xin appropriately at run time, while 
	X.B %m
	Xindicates a standard system error message as
	Xdescribed in 
	X.M intro 2 .
	XSee the source for further details.
	X.sp
	X.TY "Skipping non-man file: %s"
	X.in +5n
	XA file was found in a man directory that has no dot 
	Xin its name.
	X.in -5n
	X.sp 
	X.TY "%s has a funny extension to be in %s"
	X.in +5n
	XAn apparent man file was found whose extension doesn't
	Xmatch the name of the man file in which it was found.
	XThis restriction does not apply to 
	X.B mano
	Xsubdirectories.
	X.in -5n
	X.sp 
	X.TY "can't stat %s: %m"
	X.in +5n
	XThe 
	X.M stat 2
	Xcall returned an error.  This can be caused by a
	Xsymbolic link pointing to a non-existent file.
	X.in -5n
	X.sp 
	X.TY "can't open %s: %m"
	X.in +5n
	XThe
	X.M open 2
	Xcall returned an error, which is listed.
	X.in -5n
	X.sp 
	X.TY "can't chdir back to %s: %m"
	X.in +5n
	XAfter changing directory to one of the man subdirectories, 
	X.I makewhatis
	Xcouldn't return to the initial root man tree.  This is
	Xa fatal error.
	X.in -5n
	X.sp 
	X.TY "makewhatis: %s: found %d entries in %d files"
	X.in +5n
	XFor the given root man directory, this many separate
	Xentry points were found for this many different files.
	X.in -5n
	X.sp 
	X.TY "%s .so references non-existent %s"
	X.in +5n
	XA file contains a 
	X.B .so
	Xreference to a missing man page.
	X.in -5n
	X.sp 
	X.TY "%s's .TH thinks it's in %s"
	X.in +5n
	XThe man page's internal
	X.SB TH
	Xsection has a different idea of where it lives
	Xthan the actual file name.
	X.in -5n
	X.sp 
	X.TY "trimmed troff string macro in NAME section of %s"
	X.in +5n
	XAn irresolvable 
	X.I troff
	Xstring macro was found within the
	X.SB NAME
	Xsection of the man page.  This may cause peculiar
	X.I whatis
	Xoutput.
	X.in -5n
	X.sp 
	X.TY "%s: no separated dash in %s"
	X.in +5n
	XThe 
	X.SB NAME
	Xsection contained no dash in it to separate the list
	Xof man entries from their descriptions.  This will also 
	Xcause odd 
	X.I whatis
	Xoutput.
	X.in -5n
	X.sp 
	X.TY "%s: truncating cmdlist from %d to %d bytes for DBM's sake"
	X.in +5n
	XThe 
	X.SB NAME
	Xsection contained too many characters.  Due to built-in 
	Xlimitations of 
	X.M dbm 3X
	Xdata entries, this entry was truncated.  It will appear
	Xin 
	X.I whatis
	Xoutput with a trailing 
	X.TY \&...
	Xat the point of truncation.
	X.in -5n
	X.sp 
	X.TY "%s: forgot my own name!"
	X.in +5n
	XA man page is stored in a file name that doesn't
	Xcorrespond to any of the entries in its
	X.SB NAME
	Xsection.
	X.in -5n
	X.sp 
	X.TY "%s: no NAME lines, so has no whatis description!"
	X.in +5n
	XNo parsable entries in the 
	X.SB NAME
	Xsection were discovered.
	X.in -5n
	X.sp 
	X.TY "%s was a .so alias for %s, but %s's NAME section doesn't know it!"
	X.in +5n
	XA 
	X.B .so 
	Xreference was found to point to a man page whose own 
	X.SB NAME
	Xsection didn't contain the name of the 
	X.B .so
	Xfile.  This may be due to old man page aliases that were 
	Xnever de-installed when the base man page changed.
	X.in -5n
	X.sp 
	X.TY "can't store %s: would break DBM"
	X.in +5n
	XThere were too many entries for a topic for it
	Xto be stored without exceeding inherent
	X.M dbm 3X
	Xdata size limitations.
	X.in -5n
	X.SH NOTES
	XThis version of 
	X.I makewhatis
	Xis written entirely in the
	X.I perl
	Xprogramming language; it requires that
	X.I perl
	Xbe installed on the system to run.
	X.SH RESTRICTIONS
	XThe 
	X.SB NAME
	Xsection should be a comma-separated list
	Xof aliases for this man page, followed by white space, 
	Xa dash, more white space, and then the description.  Pages
	Xnot conforming to this rule will still be found, but a diagnostic
	Xwill be printed and their descriptions will be left blank.
	X.PP
	XMan pages should be formatted using the 
	X.M man 7
	Xmacro set.  The only exceptions to this are the man pages
	Xfrom the \fIRand MH Message Handling System\fP,
	Xwhose own internal macro set is also recognized, and Larry 
	XWall's \fB.Sh\fP section header macro.
	X.PP
	X.I makewhatis
	Xtakes much longer to run if man pages are stored in compressed form.
	X.SH BUGS
	XNot all systems have 
	X.I compress
	Xinstalled on them.
	X.SH AUTHOR
	XTom Christiansen 
	X\fI<tchrist@convex.com>\fP,
	X\s-1CONVEX\s0 Computer Corporation 
	X.SH COPYRIGHT
	XCopyright 1990 
	X\s-1CONVEX\s0 Computer Corporation.
	XYou are free to use, modify, and redistribute these scripts
	Xas you wish for non-commercial purposes provided that this
	Xnotice remains intact.
SHAR_EOF
if test 9442 -ne "`wc -c < 'makewhatis.8'`"
then
	echo shar: "error transmitting 'makewhatis.8'" '(should have been 9442 characters)'
fi
chmod 664 'makewhatis.8'
fi
echo shar: "extracting 'man.1'" '(20992 characters)'
if test -f 'man.1'
then
	echo shar: "will not over-write existing file 'man.1'"
else
sed 's/^	X//' << \SHAR_EOF > 'man.1'
	X.TH MAN 1 
	X.CX		\" probably only makes sense on Convex machines
	X.\"
	X.de SB		\" small and bold
	X.if !"\\$1"" \\s-2\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
	X..
	X.\"
	X.de T		\" switch to typewriter font
	X.ft TA		\" probably want CW if you don't have TA font
	X..
	X.\"
	X.de TY		\" put $1 in typewriter font
	X.if t .T
	X.if n ``\c
	X\\$1\c
	X.if t .ft P
	X.if n \&''\c
	X\\$2
	X..
	X.\"
	X.de M		\" man page reference
	X\\fI\\$1\\fR\\|(\\$2\)\\$3
	X..
	X.SH NAME
	Xman, apropos, whatis \- display on-line reference manual information
	X.SH SYNOPSIS
	X.B man
	X[ 
	X.B \-ltfikwuvthdgK
	X]
	X[
	X.B \-M
	X.I manpath
	X]
	X[
	X\fB-S\fIsections\fR
	X] 
	X.if n .br
	X.if n .ti +4n
	X[
	X\fB-T\fItroffproc\fR
	X] 
	X.if t .br
	X.if t .ti +4n
	X[
	X.I hwtype
	X]
	X[
	X.I section
	X]
	X.if n .br 
	X.if n .ti +4n
	X\fItopic\fB[/\fIindex\fR]
	X\&...
	X.sp
	X.B apropos
	X[
	X.B \-uvdDK
	X]
	X[
	X.B \-M
	X.I manpath
	X]
	X[
	X.I hwtype
	X] 
	X.I keyword 
	X.sp
	X.B whatis
	X[
	X.B \-uvdhD
	X]
	X[
	X.B \-M
	X.I manpath
	X]
	X[
	X.I hwtype
	X]
	X.I topic 
	X\&...
	X.SH DESCRIPTION
	XThe 
	X.I man 
	Xprogram (and its links, 
	X.I apropos
	Xand 
	X.I whatis\c
	X) formats and displays information from the on-line Programmer's
	XReference Manual.  It can display complete entries selected
	Xby topic or brief one-line summaries selected by keyword 
	X(as
	X.I apropos
	Xor with the
	X.B \-k
	Xor 
	X.B \-K
	Xflags) or by topic 
	X(as
	X.I whatis 
	Xor with
	Xthe
	X.B \-f
	Xflag).
	XWhen invoked in the simplest way, without any options and with a topic,
	Xit displays 
	Xthe corresponding manual page formatted with 
	X.M nroff 1 \&.  
	XIf the
	Xstandard output is to a terminal,
	Xthe man page is piped by default through 
	X.M more 1 , 
	Xor else through
	Xthe program specified in the user's 
	X.SB PAGER
	Xenvironment variable if set. 
	X.PP
	XMan pages are stored on-line as 
	X.I nroff
	Xsource files and are reformatted 
	Xwhenever the unformatted
	Xversion is missing or has a newer modification date than the formatted version.
	XThe formatted version of the man page stored in
	Xthe corresponding 
	X.B cat*/
	Xdirectory if it exists
	Xand is writable by the current user.
	XThus 
	X.I man1/stty.1 
	Xonce formatted
	Xis stored in 
	X.I cat1/stty.1\c
	X\&.
	XOtherwise manual pages must be reformatted each time a user wishes
	Xto view them.  
	XIf the root of the man tree from which the man page is taken contains
	Xthe file 
	X.I tmac.an\c
	X, then this file is used in lieu of the 
	Xstandard 
	X.M man 7
	Xmacros to reformat the page.  Appropriate calls to 
	X.M tbl 1
	Xand either 
	X.M neqn 1
	Xor 
	X.M eqn 1
	Xare automatically
	Xinserted as needed.
	X.SS "Section Selection"
	XSome topics occur in more than one section of the manual.
	XTo select a man page from a particular section, put the section name 
	Xin front of the topic, as in 
	X.TY "man 4 tty"\c
	X\&.  
	XFor backwards compatibility with other 
	X.I man 
	Xprograms, certain 
	Xnon-numeric sections are recognized by longer aliases: 
	X.B local
	Xmeans section 
	X.B l\c
	X, 
	X.B new
	Xmeans section
	X.B n\c
	X, 
	X.B public
	Xmeans section 
	X.B p\c
	X, and 
	X.B old
	Xmeans section 
	X.B o\c
	X\&.  
	XIn other words, 
	X.TY "man new csh"
	Xon the command line will search for a man page on the
	X.I csh
	Xin section 
	X.I n
	Xof the manual.
	X.PP
	XThe applicable topics for each component in the current
	X.SB MANPATH
	Xare sorted according to their section.
	XThe default ordering is 
	X.B ln16823457po\c
	X\&.  Thus, 
	X.M stty 1
	Xwould be displayed before 
	X.M stty 3 .
	XThis ordering can be
	Xoverridden on a site-wide basis by the system manager (see 
	X.SB NOTES
	Xsection below), a per-user basis using the 
	X.SB MANSECT
	Xenvironment variable, 
	Xor a per-command basis using the \fB-S \fIsections\fR switch.  Programmers
	Xmay prefer a default ordering beginning 
	X.B 231
	Xso that when they type 
	X.TY "man wait"
	Xthey see the man page for the system call rather than the one for the shell command
	Xof the same name.
	XIf multi-character sections exist (\fIe.g.\fR some systems have a 
	X.B man1m
	Xsection)
	Xor subsection ordering is desired, then colons must be used to separate
	Xthe sections.  A \s-1FORTRAN\s0 programmer might prefer to set his 
	X.SB MANSECT
	Xto 
	X.B 3f:2:3:1:6:8\c
	X, so that when he asks for the 
	Xmanual page for 
	X.I system\c
	X, he gets 
	X.M system 3F
	Xrather than the
	XC function of the same name.
	X.PP 
	XCase is significant for
	Xthe topic itself, but not for the section.  This allows 
	Xyou to make a distinction between 
	X.M cc 1 , 
	Xthe C compiler,
	Xand 
	X.M CC 1 , 
	Xthe C++ translator.  However, section 
	X.B 3S
	Xis interpreted as section 
	X.B 3s
	Xto accommodate users
	Xwho see a reference to the man page for 
	X.M printf 3S ,
	Xand don't realize that it's stored in the file 
	X.B printf.3s\c
	X\&.
	X.SS "Search Strategy"
	XThe 
	X.I man
	Xprogram by default consults the 
	X.SB MANPATH 
	Xenvironment variable for a list of complete man trees.
	XIf this variable is not set, then the user's 
	X.SB PATH
	Xenvironment variable will be consulted instead.  This way, if
	X.I /usr/local/bin 
	Xis before
	X.I /usr/bin
	Xin the PATH variable, then 
	X.I /usr/local/man 
	Xwill be before
	X.I /usr/man
	Xin the dynamically determined
	X.SB MANPATH
	Xvariable.  This is nice because it means the user need only add a 
	X.SB PATH
	Xcomponent, and the 
	X.SB MANPATH
	Xwill be automatically updated apppropriately.
	XThis search
	Xorder can be overridden on a site-wide basis by the system manager (see
	X.SB NOTES
	Xsection below) or on a per-user basis by setting the 
	Xenvironment variable 
	X.SB MANPATH .  
	XThis is a colon-separated 
	Xlist of directory names that contains subdirectories
	Xof the form 
	X.B man*/\c
	X\&.  A user keeping his own man pages under his home directory 
	Xmight place a line like the following in his 
	X.BI ~ /.cshrc 
	Xfile:
	X.in +5n
	X.TY "setenv MANPATH $HOME/man:/usr/local/man:/usr/man"
	X.in -5n
	XThe 
	X.SB MANPATH
	Xmay also be set on a per-command basis by using the 
	X.B \-M
	Xcommand-line.
	X.PP
	XIt is possible to install several complete sets
	Xof man pages on one host.  These alternate sets are 
	Xassumed to be installed in 
	X\fB\s-2MANALT\s0\fI/subdir\fR, where 
	X.SB MANALT
	Xis an environment variable defaulting to 
	X.I /usr/local/man
	Xand
	X.I subdir
	Xis assumed to be a complete man tree.  
	XIf at least non-switch two arguments are supplied,
	Xthen the 
	X.SB MANALT
	Xdirectory is consulted
	Xto see whether it contains a sub-directory whose names is the
	Xfirst argument.  This makes it easy to say things like 
	X.TY "man sun csh"
	Xto read the 
	X.I csh
	Xman page from the installed set of 
	X.I sun
	Xman pages.  This is equivalent to saying 
	X.TY "man -M /usr/local/bin/sun csh" " (assuming"
	X.SB MANALT
	Xis not set).
	X.SS "Indexing"
	XVery long man pages are often broken up into several major 
	Xsubsections, whose tables of contents can be listed with the 
	X.B \-i
	Xswitch.
	XTo access one of these subsections directly,
	Xspecify \fB/\fIindex\fR,
	Xwhere 
	X.I /index
	Xis the name of the subsection.
	XFor example, 
	Xto see the section on expressions in the 
	X.M csh 1
	Xman page, use 
	X.TY "man csh/expr" 
	Xto skip to that section first.
	XIf 
	X.I index
	Xis not a valid section or 
	Xsubsection header, or if none is given, 
	Xa list of all valid section
	Xheaders is displayed and the user is prompted 
	Xto select one.  The special form of a missing subsection 
	Xafter the slash means to go into continuous menu mode, returning to the
	Xsection menu after the manual page has been displayed.
	X.PP
	XThe match against the index entries is not case-sensitive,
	Xnor is it required to be at the beginning
	Xof the string.  For example, this allows
	X.TY /expr
	Xto be 
	Xused to look up the
	X.TY "Regular Expressions"
	Xsection.
	XHowever, matches that 
	X.I do
	Xstart at the front of the 
	Xheader are selected before those that do not.  A 
	Xnumeric section index as listed by the 
	X.B \-i
	Xflag may also be given, with an index of 
	X.B 0
	Xmeaning the whole page.  
	X.PP
	XMan page indices (tables of contents) are generated automatically when needed.
	XTo save time,
	Xif a writable 
	X.B idx*/
	Xsubdirectory exists in the root
	Xof the man tree, the index is left there under the
	Xsame name as its man page for quicker
	Xaccess in the future.  Indices older than their 
	Xparent man page are rebuilt upon demand.
	X.PP 
	XAs a special case of indexing, the form
	X.I //string
	Xstarts the 
	X.SB PAGER
	Xat an arbitrary 
	X.I string
	Xin the text of the man page
	Xrather than at a subsection index.
	X.PP
	XNote that the 
	X.I /index
	Xfeature may not be used in conjunction with the 
	X.B \-l
	X(local file) switch.  The 
	X.B \-i
	Xswitch may still 
	Xbe used with local files.
	X.SS "Online Problem Reports"
	XSome vendors provide their customers with electronically
	Xreadable problem reports; also, some sites may wish to 
	Xmaintain their own list of known problems. 
	XTo support inclusion of these in 
	Xthe man pages, the 
	X.I man
	Xprogram knows to look in a set of 
	X.B pr*
	Xsubdirectories for additional source.  For example, if you
	Xare reading the man page contained in 
	X\fI/usr/man/man1/foo.1\fP,
	Xthen if there exists a file called 
	X\fI/usr/man/pr1/foo.1\fP, this will be appended to the
	Xdata passed to 
	X.I nroff
	Xor 
	X.I troff
	Xas an additional 
	X.SB "KNOWN PROBLEMS"
	Xsection.  These files should be in 
	X.I nroff
	Xformat.  
	X.SH OPTIONS
	X.TP 
	X.BI \-M manpath
	XChanges the search path for finding man pages for just
	Xthis command, overriding the current 
	X.SB MANPATH
	Xenvironment variable or system default.
	XSee the section on 
	X.SB "Search Strategy"
	Xfor further details.
	X.TP 
	X.BI \-S sections
	Xsets the section and subsection ordering for just
	Xthis command, overriding the 
	Xcurrent 
	X.SB MANSECT 
	Xenvironment variables or system default.
	XSee the 
	X.B "Section Selection"
	Xfor further details.
	X.TP
	X.B \-f
	Xdirects
	X.I man
	Xto print out the applicable one-line descriptions
	Xfor each corresponding 
	X.I topic\c
	X\&.  
	XThese one-line descriptions are stored in separate 
	X.I whatis
	Xfiles for each component in the 
	Xspecified 
	X.SB MANPATH
	X\&.  If 
	X.M dbm 3X
	Xversions of these
	Xdatabases exist, these are used for more rapid location of manual
	Xpages.  See 
	X.M makewhatis 8
	Xfor directions on generating the 
	X.I "whatis"
	Xdatabases.  
	XThis switch is automatically enabled if 
	X.I man
	Xis invoked as 
	X.IR whatis .
	X.TP
	X.B \-k
	Xdirect
	X.I man
	Xto search the 
	X.I whatis
	Xdatabases for any entry 
	Xmatching the given 
	X.I keyword\c
	X\&.  
	XThis is useful when the precise topic is unknown; it reports
	Xthe topics that have to do with the given keywords, according
	Xto their 
	X.I whatis
	Xdescriptions.
	XOutput will be sent to the user's
	X.SB PAGER .
	XThis switch is automatically enabled if 
	X.I man
	Xis invoked as 
	X.IR apropos .
	X.TP 
	X.B \-K
	Xsame as
	X.B \-k
	Xexcept regular expressions as in 
	X.M egrep 1
	Xmay be used in the 
	X.I keywords\c
	X\&.
	X.TP 
	X.B \-g
	XGrep through all man pages for one or more 
	X.I perl
	Xexpressions.  Compressed man pages will be 
	Xcorrectly processed
	Xby 
	X.M zcat 1L .
	X.TP
	X.B \-t
	Xis used to typeset the manual pages, usually
	Xusing 
	X.M troff 1L
	Xor a front-end for the same.
	XIf the 
	Xdefault system typesetter is not desired, it can be overridden 
	Xeither with the 
	X.SB TROFF
	Xenvironment variable or the 
	X.B \-T
	Xflag.
	X.TP 
	X.BI \-T troffproc
	Xselects an alternate typesetting program, overriding
	Xthe current 
	X.SB TROFF
	Xenvironment variable or system default.
	XIt is most 
	Xoften used to select a previewer
	Xfor workstations that support previewing of 
	X.I troff
	Xoutput.
	X.TP
	X.B \-l
	Xis used with specific file names rather than with
	Xtopics.  The same processing as 
	X.I man
	Xwould perform on a system 
	Xmanual page will be performed on the given file.  This is useful
	Xwhen first writing new manual pages or viewing ones not yet installed.
	XIt may be used in conjunction with other switches, such as 
	X.B \-t\c
	X\&.  The indexing feature is not available for local man pages except
	Xvia the 
	X.B \-i
	Xswitch.
	X.TP
	X.B \-w
	Xis used to determine the full pathnames of 
	Xthe files that 
	X.I man 
	Xwould display for the given topic.  This is useful
	Xwhen the same topic occurs in more than one section of the manual or
	Xin more than one of the components in the supplied 
	X.SB MANPATH .
	XThe files are listed in the order in which they would be presented
	Xto the user.  
	X.TP
	X.B \-a
	Xdisplays all man pages for all possible matches for a given 
	Xtopic.  Its effect is similar to calling 
	X.I man 
	Xon all the files returned by the
	X.B \-w
	Xswitch.
	X.TP 
	X.B \-i
	Xdisplays
	Xthe complete section and subsection index
	Xfor a given topic.  
	X.TP
	X.B \-v
	Xprints out the current revision of the program
	Xas stored by 
	X.M rcs 1 .
	X.TP
	X.B \-u
	Xdisplays a long usage message, piped through the user's 
	X.SB PAGER .  
	XIt includes the current defaults for 
	X.SB PAGER ,
	X.SB MANPATH ,
	X.SB MANSECT ,
	X.SB MANALT ,
	Xand 
	X.SB TROFF .
	X.TP 
	X.B \-h
	Xforces 
	X.I "man"
	Xto ignore the 
	X.I whatis
	Xdatabases and search for its manual pages the slow way.  This is the
	Xdefault behavior if no 
	X.I whatis
	Xdatabase has been created for 
	Xa particular man tree.
	X.TP
	X.B \-d
	Xtriggers debugging output.  All externally invoked programs
	Xsuch as 
	X.I nroff
	Xand 
	X.I egrep
	Xwill have their arguments displayed
	Xbefore they are called.  Certain other debugging information is also printed.
	X.TP 
	X.B \-D
	Xcauses embedded backspaces and their preceding characters
	Xin cat pages to be stripped upon 
	Xoutput.  This is useful for producing utterly clean output,
	Xsuch as when being viewed in an 
	X.M emacs 1
	Xwindow.
	X.SH EXAMPLES
	X.T
	X.nf
	X.ta 20
	X.\"	.ne 5
	Xman stty	# show me the first stty man page
	Xman -w stty	# which stty man pages are there?
	Xman 3 stty	# show me the one from section 3
	Xman -a tty	# show all man pages on tty