The Answer to All Man's Problems (part 1 of 6)
Tom Christiansen
tchrist at convex.COM
Tue Jan 8 09:14:40 AEST 1991
#! /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 at 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
More information about the Alt.sources
mailing list