diff options
Diffstat (limited to 'man/man1')
| -rw-r--r-- | man/man1/apropos.man1 | 267 | ||||
| -rw-r--r-- | man/man1/lexgrog.man1 | 219 | ||||
| -rw-r--r-- | man/man1/man.man1 | 1418 | ||||
| -rw-r--r-- | man/man1/manconv.man1 | 78 | ||||
| -rw-r--r-- | man/man1/manpath.man1 | 137 | ||||
| -rw-r--r-- | man/man1/whatis.man1 | 262 | ||||
| -rw-r--r-- | man/man1/zsoelim.man1 | 80 |
7 files changed, 2461 insertions, 0 deletions
diff --git a/man/man1/apropos.man1 b/man/man1/apropos.man1 new file mode 100644 index 0000000..43c3b3d --- /dev/null +++ b/man/man1/apropos.man1 @@ -0,0 +1,267 @@ +.\" Man page for %apropos% +.\" +.\" Copyright (C), 1994, 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.\" +.\" Sat Oct 29 13:09:31 GMT 1994 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.pc +.TH %thapropos% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%apropos% \- search the manual page names and descriptions +.SH SYNOPSIS +.B %apropos% +.RB [\| \-dalv?V \|] +.RB [\| \-e \||\| \-w \||\| \-r\c +\|] +.RB [\| \-s +.IR list \|] +.RB [\| \-m +.IR system \|[\|,.\|.\|.\|]\|] +.RB [\| \-M +.IR path \|] +.RB [\| \-L +.IR locale \|] +.RB [\| \-C +.IR file \|] +.I keyword +\&.\|.\|. +.SH DESCRIPTION +Each manual page has a short description available within it. +.B %apropos% +searches the descriptions for instances of +.IR keyword . + +.I keyword +is usually a regular expression, as if +.RB ( \-r ) +was used, or +may contain wildcards +.RB ( \-w ), +or match the exact keyword +.RB ( \-e ). +Using these options, it may be necessary to quote the +.I keyword +or escape (\\) the special characters to stop the shell from interpreting +them. + +The standard matching rules allow matches to be made against the page name +and word boundaries in the description. + +The database searched by +.B %apropos% +is updated by the +.B %mandb% +program. +Depending on your installation, this may be run by a periodic cron job, or +may need to be run manually after new manual pages have been installed. +.SH OPTIONS +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-v ", " \-\-verbose +Print verbose warning messages. +.TP +.if !'po4a'hide' .BR \-r ", " \-\-regex +Interpret each keyword as a regular expression. +This is the default behaviour. +Each keyword will be matched against the page names and the descriptions +independently. +It can match any part of either. +The match is not limited to word boundaries. +.TP +.if !'po4a'hide' .BR \-w ", " \-\-wildcard +Interpret each keyword as a pattern containing shell style wildcards. +Each keyword will be matched against the page names and the descriptions +independently. +If +.B \-\-exact +is also used, +a match will only be found if an expanded keyword matches an entire +description or page name. +Otherwise the keyword is also allowed to match on word boundaries in the +description. +.TP +.if !'po4a'hide' .BR \-e ", " \-\-exact +Each keyword will be exactly matched against the page names and the +descriptions. +.TP +.if !'po4a'hide' .BR \-a ", " \-\-and +Only display items that match all the supplied keywords. +The default is to display items that match any keyword. +.TP +.if !'po4a'hide' .BR \-l ", " \-\-long +Do not trim output to the terminal width. +Normally, output will be truncated to the terminal width to avoid ugly +results from poorly-written +.B NAME +sections. +.TP +\fB\-s\fP \fIlist\fP, \fB\-\-sections\fP \fIlist\fP, \fB\-\-section\fP \fIlist\fP +Search only the given manual sections. +.I list +is a colon- or comma-separated list of sections. +If an entry in +.I list +is a simple section, for example "3", then the displayed list of +descriptions will include pages in sections "3", "3perl", "3x", and so on; +while if an entry in +.I list +has an extension, for example "3perl", then the list will only include +pages in that exact part of the manual section. +.\" +.\" Due to the rather silly limit of 6 args per request in some `native' +.\" *roff compilers, we have do the following to get the two-line +.\" hanging tag on one line. .PP to begin a new paragraph, then the +.\" tag, then .RS (start relative indent), the text, finally .RE +.\" (end relative indent). +.\" +.PP +.B \-m +.I system\c +\|[\|,.\|.\|.\|]\|, +.BI \-\-systems= system\c +\|[\|,.\|.\|.\|] +.RS +If this system has access to other operating system's manual page +descriptions, they can be searched using this option. +To search NewOS's manual page descriptions, use the option +.B \-m +.BR NewOS . + +The +.I system +specified can be a combination of comma-delimited operating system names. +To include a search of the native operating system's +.B whatis +descriptions, include the system name +.B man +in the argument string. +This option will override the +.RB $ SYSTEM +environment variable. +.RE +.TP +.BI \-M\ path \fR,\ \fB\-\-manpath= path +Specify an alternate set of colon-delimited manual page hierarchies to +search. +By default, +.B %program% +uses the +.RB $ MANPATH +environment variable, unless it is empty or unset, in which case it will +determine an appropriate manpath based on your +.RB $ PATH +environment variable. +This option overrides the contents of +.RB $ MANPATH . +.TP +.BI \-L\ locale \fR,\ \fB\-\-locale= locale +.B %program% +will normally determine your current locale by a call to the C function +.BR setlocale (3) +which interrogates various environment variables, possibly including +.RB $ LC_MESSAGES +and +.RB $ LANG . +To temporarily override the determined value, use this option to supply a +.I locale +string directly to +.BR %program% . +Note that it will not take effect until the search for pages actually +begins. +Output such as the help message will always be displayed in the initially +determined locale. +.TP +.BI \-C\ file \fR,\ \fB\-\-config\-file= file +Use this user configuration file rather than the default of +.IR ~/.manpath . +.TP +.if !'po4a'hide' .BR \-? ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-\-usage +Print a short usage message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "EXIT STATUS" +.TP +.if !'po4a'hide' .B 0 +Successful program execution. +.TP +.if !'po4a'hide' .B 1 +Usage, syntax or configuration file error. +.TP +.if !'po4a'hide' .B 2 +Operational error. +.TP +.if !'po4a'hide' .B 16 +Nothing was found that matched the criteria specified. +.SH ENVIRONMENT +.TP +.if !'po4a'hide' .B SYSTEM +If +.RB $ SYSTEM +is set, it will have the same effect as if it had been specified as the +argument to the +.B \-m +option. +.TP +.if !'po4a'hide' .B MANPATH +If +.RB $ MANPATH +is set, its value is interpreted as the colon-delimited manual page +hierarchy search path to use. +.TP +.if !'po4a'hide' .B MANWIDTH +If +.RB $ MANWIDTH +is set, its value is used as the terminal width (see the +.B \-\-long +option). +If it is not set, the terminal width will be calculated using the value of +.RB $ COLUMNS , +an +.BR ioctl (2) +if available, or falling back to 80 characters if all else fails. +.TP +.if !'po4a'hide' .B POSIXLY_CORRECT +If +.RB $ POSIXLY_CORRECT +is set, even to a null value, the default +.B %apropos% +search will be as an extended regex +.RB ( \-r ). +Nowadays, this is the default behaviour anyway. +.SH FILES +.TP +.if !'po4a'hide' .I /usr/share/man/index.(bt|db|dir|pag) +A traditional global +.I index +database cache. +.TP +.if !'po4a'hide' .I /var/cache/man/index.(bt|db|dir|pag) +An FHS +compliant global +.I index +database cache. +.TP +.if !'po4a'hide' .I /usr/share/man/\|.\|.\|.\|/whatis +A traditional +.B whatis +text database. +.SH "SEE ALSO" +.if !'po4a'hide' .BR %man% (1), +.if !'po4a'hide' .BR %whatis% (1), +.if !'po4a'hide' .BR %mandb% (8) +.SH AUTHOR +.nf +.if !'po4a'hide' Wilf. (G.Wilford@ee.surrey.ac.uk). +.if !'po4a'hide' Fabrizio Polacco (fpolacco@debian.org). +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi diff --git a/man/man1/lexgrog.man1 b/man/man1/lexgrog.man1 new file mode 100644 index 0000000..b1f8896 --- /dev/null +++ b/man/man1/lexgrog.man1 @@ -0,0 +1,219 @@ +.\" Man page for lexgrog +.\" +.\" Copyright (c) 2001 Colin Watson <cjwatson@debian.org> +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.pc +.TH LEXGROG 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +lexgrog \- parse header information in man pages +.SH SYNOPSIS +.B lexgrog +.RB [\| \-m \||\| -c \|] +.RB [\| \-dfw?V \|] +.RB [\| \-E +.IR encoding \|] +.I file +\&.\|.\|. +.SH DESCRIPTION +.B lexgrog +is an implementation of the traditional \(lqgroff guess\(rq utility in +.BR lex . +It reads the list of files on its command line as either man page source +files or preformatted \(lqcat\(rq pages, and displays their name and +description as used by +.B apropos +and +.BR whatis , +the list of preprocessing filters required by the man page before it is +passed to +.B nroff +or +.BR troff , +or both. +.PP +If its input is badly formatted, +.B lexgrog +will print \(lqparse failed\(rq; this may be useful for external +programs that need to check man pages for correctness. +If one of +.BR lexgrog 's +input files is \(lq\-\(rq, it will read from standard input; if any input +file is compressed, a decompressed version will be read automatically. +.SH OPTIONS +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-m ", " \-\-man +Parse input as man page source files. +This is the default if neither +.B \-\-man +nor +.B \-\-cat +is given. +.TP +.if !'po4a'hide' .BR \-c ", " \-\-cat +Parse input as preformatted man pages (\(lqcat pages\(rq). +.B \-\-man +and +.B \-\-cat +may not be given simultaneously. +.TP +.if !'po4a'hide' .BR \-w ", " \-\-whatis +Display the name and description from the man page's header, as used by +.B apropos +and +.BR whatis . +This is the default if neither +.B \-\-whatis +nor +.B \-\-filters +is given. +.TP +.if !'po4a'hide' .BR \-f ", " \-\-filters +Display the list of filters needed to preprocess the man page before +formatting with +.B nroff +or +.BR troff . +.TP +\fB\-E\fP \fIencoding\fP, \fB\-\-encoding\fP \fIencoding\fP +Override the guessed character set for the page to +.IR encoding . +.TP +.if !'po4a'hide' .BR \-? ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-\-usage +Print a short usage message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "EXIT STATUS" +.TP +.if !'po4a'hide' .B 0 +Successful program execution. +.TP +.if !'po4a'hide' .B 1 +Usage error. +.TP +.if !'po4a'hide' .B 2 +.B lexgrog +failed to parse one or more of its input files. +.SH EXAMPLES +.nf + $ lexgrog man.1 + man.1: "man \- an interface to the on-line reference manuals" + $ lexgrog \-fw man.1 + man.1 (t): "man \- an interface to the on-line reference manuals" + $ lexgrog \-c whatis.cat1 + whatis.cat1: "whatis \- display manual page descriptions" + $ lexgrog broken.1 + broken.1: parse failed +.fi +.SH WHATIS PARSING +.B %mandb% +(which uses the same code as +.BR lexgrog ) +parses the +.B NAME +section at the top of each manual page looking for names and descriptions +of the features documented in each. +While the parser is quite tolerant, as it has to cope with a number of +different forms that have historically been used, it may sometimes fail to +extract the required information. +.PP +When using the traditional +.I man +macro set, a correct +.B NAME +section looks something like this: +.PP +.RS +.ft CW +.nf +\&.SH NAME +foo \e\- program to do something +.fi +.ft P +.RE +.PP +Some manual pagers require the \(oq\e\-\(cq to be exactly as shown; +.B %mandb% +is more tolerant, but for compatibility with other systems it is +nevertheless a good idea to retain the backslash. +.PP +On the left-hand side, there may be several names, separated by commas. +Names containing whitespace will be ignored to avoid pathological behaviour +on certain ill-formed +.B NAME +sections. +The text on the right-hand side is free-form, and may be spread over +multiple lines. +If several features with different descriptions are being documented in the +same manual page, the following form is therefore used: +.PP +.RS +.ft CW +.nf +\&.SH NAME +foo, bar \e\- programs to do something +\&.br +baz \e\- program to do nothing +.fi +.ft P +.RE +.PP +(A macro which starts a new paragraph, like \f(CW.PP\fP, may be used instead +of the break macro \f(CW.br\fP.) +.PP +When using the BSD-derived +.I mdoc +macro set, a correct +.B NAME +section looks something like this: +.PP +.RS +.ft CW +.nf +\&.Sh NAME +\&.Nm foo +\&.Nd program to do something +.fi +.ft P +.RE + +There are several common reasons why whatis parsing fails. +Sometimes authors of manual pages replace \(oq.SH NAME\(cq with +\(oq.SH MYPROGRAM\(cq, and then +.B %mandb% +cannot find the section from which to extract the information it needs. +Sometimes authors include a NAME section, but place free-form text there +rather than \(oqname \e\- description\(cq. +However, any syntax resembling the above should be accepted. +.SH "SEE ALSO" +.if !'po4a'hide' .IR apropos (1), +.if !'po4a'hide' .IR man (1), +.if !'po4a'hide' .IR whatis (1), +.if !'po4a'hide' .IR mandb (8) +.SH NOTES +.B lexgrog +attempts to parse files containing .so requests, but will only be able +to do so correctly if the files are properly installed in a manual page +hierarchy. +.SH AUTHOR +The code used by +.B lexgrog +to scan man pages was written by: +.PP +.nf +.if !'po4a'hide' Wilf. (G.Wilford@ee.surrey.ac.uk). +.if !'po4a'hide' Fabrizio Polacco (fpolacco@debian.org). +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi +.PP +Colin Watson wrote the current incarnation of the command-line +front-end, as well as this man page. diff --git a/man/man1/man.man1 b/man/man1/man.man1 new file mode 100644 index 0000000..740ae98 --- /dev/null +++ b/man/man1/man.man1 @@ -0,0 +1,1418 @@ +'\" t +.\" ** The above line should force tbl to be a preprocessor ** +.\" Man page for man +.\" +.\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.) +.\" Copyright (C) 2001, 2002, 2003, 2006, 2007, 2008 Colin Watson. +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.\" +.\" Sat Oct 29 13:09:31 GMT 1994 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.pc +.TH %thman% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%man% \- an interface to the on-line reference manuals +.SH SYNOPSIS +.\" The general command line +.B %man% +.RB [\| \-C +.IR file \|] +.RB [\| \-d \|] +.RB [\| \-D \|] +.RB [\| \-\-warnings \|\c +.RI [\|= warnings \|]\|] +.RB [\| \-R +.IR encoding \|] +.RB [\| \-L +.IR locale \|] +.RB [\| \-m +.IR system \|[\|,.\|.\|.\|]\|] +.RB [\| \-M +.IR path \|] +.RB [\| \-S +.IR list \|] +.RB [\| \-e +.IR extension \|] +.RB [\| \-i \||\| \-I \|] +.RB [\| \-\-regex \||\| \-\-wildcard \|] +.RB [\| \-\-names\-only \|] +.RB [\| \-a \|] +.RB [\| \-u \|] +.RB [\| \-\-no\-subpages \|] +.RB [\| \-P +.IR pager \|] +.RB [\| \-r +.IR prompt \|] +.RB [\| \-7 \|] +.RB [\| \-E +.IR encoding \|] +.RB [\| \-\-no\-hyphenation \|] +.RB [\| \-\-no\-justification \|] +.RB [\| \-p +.IR string \|] +.RB [\| \-t \|] +.RB [\| \-T \|\c +.RI [\| device \|]\|] +.RB [\| \-H \|\c +.RI [\| browser \|]\|] +.RB [\| \-X \|\c +.RI [\| dpi \|]\|] +.RB [\| \-Z \|] +.RI [\|[\| section \|] +.IR page [.\| section \|]\ \|.\|.\|.\|]\ \.\|.\|.\& +.\" The apropos command line +.br +.B %man% +.B \-k +.RI [\| apropos +.IR options \|] +.I regexp +\&.\|.\|.\& +.\" The --global-apropos command line +.br +.B %man% +.B \-K +.RB [\| \-w \||\| \-W \|] +.RB [\| \-S +.IR list \|] +.RB [\| \-i \||\| \-I \|] +.RB [\| \-\-regex \|] +.RI [\| section \|] +.IR term \ .\|.\|.\& +.\" The whatis command line +.br +.B %man% +.B \-f +.RI [\| whatis +.IR options \|] +.I page +\&.\|.\|.\& +.\" The --local command line +.br +.B %man% +.B \-l +.RB [\| \-C +.IR file \|] +.RB [\| \-d \|] +.RB [\| \-D \|] +.RB [\| \-\-warnings \|\c +.RI [\|= warnings \|]\|] +.RB [\| \-R +.IR encoding \|] +.RB [\| \-L +.IR locale \|] +.RB [\| \-P +.IR pager \|] +.RB [\| \-r +.IR prompt \|] +.RB [\| \-7 \|] +.RB [\| \-E +.IR encoding \|] +.RB [\| \-p +.IR string \|] +.RB [\| \-t \|] +.RB [\| \-T \|\c +.RI [\| device \|]\|] +.RB [\| \-H \|\c +.RI [\| browser \|]\|] +.RB [\| \-X \|\c +.RI [\| dpi \|]\|] +.RB [\| \-Z \|] +.I file +\&.\|.\|.\& +.\" The --where/--where-cat command line +.br +.B %man% +.BR \-w \||\| \-W +.RB [\| \-C +.IR file \|] +.RB [\| \-d \|] +.RB [\| \-D \|] +.I page +\&.\|.\|.\& +.\" The --catman command line +.br +.B %man% +.B \-c +.RB [\| \-C +.IR file \|] +.RB [\| \-d \|] +.RB [\| \-D \|] +.I page +\&.\|.\|.\& +.\" --help and --version +.br +.B %man% +.RB [\| \-?V \|] +.SH DESCRIPTION +.B %man% +is the system's manual pager. +Each +.I page +argument given to +.B %man% +is normally the name of a program, utility or function. +The +.I manual page +associated with each of these arguments is then found and displayed. +A +.IR section , +if provided, will direct +.B %man% +to look only in that +.I section +of the manual. +The default action is to search in all of the available +.IR sections +following a pre-defined order ("%sections%" by default, unless overridden by +the +.B SECTION +directive in +.IR %manpath_config_file% ), +and to show only the first +.I page +found, even if +.I page +exists in several +.IR sections . + +The table below shows the +.I section +numbers of the manual followed by the types of pages they contain. + +.TS +tab (@); +l lx. +1@T{ +Executable programs or shell commands +T} +2@T{ +System calls (functions provided by the kernel) +T} +3@T{ +Library calls (functions within program libraries) +T} +4@T{ +Special files (usually found in \fI/dev\/\fR) +T} +5@T{ +File formats and conventions eg \fI/etc/passwd\fR +T} +6@T{ +Games +T} +7@T{ +Miscellaneous (including macro packages and conventions), +e.g.\& \fBman\fR(7), \fBgroff\fR(7) +T} +8@T{ +System administration commands (usually only for root) +T} +9@T{ +Kernel routines [\|Non standard\|] +T} +.TE + +A manual +.I page +consists of several sections. + +Conventional section names include +.BR NAME , +.BR SYNOPSIS , +.BR CONFIGURATION , +.BR DESCRIPTION , +.BR OPTIONS , +.BR EXIT\ STATUS , +.BR RETURN\ VALUE , +.BR ERRORS , +.BR ENVIRONMENT , +.BR FILES , +.BR VERSIONS , +.BR CONFORMING\ TO , +.BR NOTES , +.BR BUGS , +.BR EXAMPLE , +.BR AUTHORS , +and +.BR SEE\ ALSO . + +The following conventions apply to the +.B SYNOPSIS +section and can be used as a guide in other sections. + +.TS +tab (@); +l lx. +\fBbold text\fR@T{ +type exactly as shown. +T} +\fIitalic text\fR@T{ +replace with appropriate argument. +T} +[\|\fB\-abc\fR\|]@T{ +any or all arguments within [ ] are optional. +T} +\fB\-a\|\fR|\|\fB\-b\fR@T{ +options delimited by | cannot be used together. +T} +\fIargument\fR .\|.\|.@T{ +\fIargument\fR is repeatable. +T} +[\|\fIexpression\fR\|]\fR .\|.\|.@T{ +\fRentire \fIexpression\fR\ within [ ] is repeatable. +T} +.TE + +Exact rendering may vary depending on the output device. +For instance, man will usually not be able to render italics when running in +a terminal, and will typically use underlined or coloured text instead. + +The command or function illustration is a pattern that should match all +possible invocations. +In some cases it is advisable to illustrate several exclusive invocations +as is shown in the +.B SYNOPSIS +section of this manual page. +.SH EXAMPLES +.TP \w'%man%\ 'u +.BI %man% \ ls +Display the manual page for the +.I item +(program) +.IR ls . +.TP +\fB%man% \fIman\fR.\fI7 +Display the manual page for macro package +.I man +from section \fI7\fR. +.TP +.BI %man%\ \-a \ intro +Display, in succession, all of the available +.I intro +manual pages contained within the manual. +It is possible to quit between successive displays or skip any of them. +.TP +\fB%man% \-t \fIalias \fR|\fI lpr \-Pps +Format the manual page referenced by +.RI ` alias ', +usually a shell manual page, into the default +.B troff +or +.B groff +format and pipe it to the printer named +.IR ps . +The default output for +.B groff +is usually PostScript. +.B %man% \-\-help +should advise as to which processor is bound to the +.B \-t +option. +.TP +.BI "%man% \-l \-T" "dvi ./foo.1x.gz" " > " ./foo.1x.dvi +This command will decompress and format the nroff source manual page +.I ./foo.1x.gz +into a +.B device independent (dvi) +file. +The redirection is necessary as the +.B \-T +flag causes output to be directed to +.B stdout +with no pager. +The output could be viewed with a program such as +.B xdvi +or further processed into PostScript using a program such as +.BR dvips. +.TP +.BI %man%\ \-k \ printf +Search the short descriptions and manual page names for the keyword +.I printf +as regular expression. +Print out any matches. +Equivalent to +.BI %apropos% \ printf . +.TP +.BI %man%\ \-f \ smail +Lookup the manual pages referenced by +.I smail +and print out the short descriptions of any found. +Equivalent to +.BI %whatis% \ smail . +.SH OVERVIEW +Many options are available to +.B %man% +in order to give as much flexibility as possible to the user. +Changes can be made to the search path, section order, output processor, +and other behaviours and operations detailed below. + +If set, various environment variables are interrogated to determine +the operation of +.BR %man% . +It is possible to set the `catch all' variable +.RB $ MANOPT +to any string in command line format with the exception that any spaces +used as part of an option's argument must be escaped (preceded by a +backslash). +.B %man% +will parse +.RB $ MANOPT +prior to parsing its own command line. +Those options requiring an argument will be overridden by the same options +found on the command line. +To reset all of the options set in +.RB $ MANOPT , +.B \-D +can be specified as the initial command line option. +This will allow %man% to `forget' about the options specified in +.RB $ MANOPT +although they must still have been valid. + +The manual pager utilities packaged as +.B man-db +make extensive use of +.B index +database caches. +These caches contain information such as where each manual page can be +found on the filesystem and what its +.I whatis +(short one line description of the man page) contains, and allow +.B %man% +to run faster than if it had to search the filesystem each time to find the +appropriate manual page. +If requested using the +.B \-u +option, +.B man +will ensure that the caches remain consistent, which can obviate the +need to manually run software to update traditional +.I whatis +text databases. + +If +.B %man% +cannot find a +.B %mandb% +initiated +.B index +database for a particular manual page hierarchy, it will still search for +the requested manual pages, although file globbing will be necessary to +search within that hierarchy. +If +.B %whatis% +or +.B %apropos% +fails to find an +.B index +it will try to extract information from a traditional +.I whatis +database instead. +.\"`User' manual page hierarchies will have +.\".B index +.\"caches created `on the fly'. + +These utilities support compressed source nroff files having, by default, the +extensions of +.BR .Z ", " .z " and " .gz . +It is possible to deal with any compression extension, but this information +must be known at compile time. +Also, by default, any cat pages produced are compressed using +.BR gzip . +Each `global' manual page hierarchy such as +.I /usr/share/man +or +.I /usr/X11R6/man +may have any directory as its cat page hierarchy. +Traditionally the cat pages are stored under the same hierarchy as the man +pages, but for reasons such as those specified in the +.BR "File Hierarchy Standard (FHS)" , +it may be better to store them elsewhere. +For details on how to do this, please read +.BR manpath (5). +For details on why to do this, read the standard. + +International support is available with this package. +Native language manual pages are accessible (if available on your system) +via use of +.I locale +functions. +To activate such support, it is necessary to set either +.RB $ LC_MESSAGES , +.RB $ LANG +or another system dependent environment variable to your language locale, +usually specified in the +.B POSIX 1003.1 +based format: + +.\" +.\" Need a \c to make sure we don't get a space where we don't want one +.\" +.RI < language >[\|\c +.B _\c +.RI < territory >\|[\|\c +.B .\c +.RI < character-set >\|[\|\c +.B ,\c +.RI < version >\|]\|]\|] + +If the desired page is available in your +.IR locale , +it will be displayed in lieu of the standard +(usually American English) page. + +Support for international message catalogues is also featured in this +package and can be activated in the same way, again if available. +If you find that the manual pages and message catalogues supplied with this +package are not available in your native language and you would like to +supply them, please contact the maintainer who will be coordinating such +activity. + +For information regarding other features and extensions available with this +manual pager, please read the documents supplied with the package. +.SH DEFAULTS +.B %man% +will search for the desired manual pages within the +.I index +database caches. If the +.B \-u +option is given, a cache consistency check is performed to ensure the +databases accurately reflect the filesystem. +If this option is always given, it is not generally necessary to run +.B %mandb% +after the caches are initially created, unless a cache becomes corrupt. +However, the cache consistency check can be slow on systems with many +manual pages installed, so it is not performed by default, and system +administrators may wish to run +.B %mandb% +every week or so to keep the database caches fresh. +To forestall problems caused by outdated caches, +.B %man% +will fall back to file globbing if a cache lookup fails, just as it would +if no cache was present. + +Once a manual page has been located, a check is performed to find out if a +relative preformatted `cat' file already exists and is newer than the nroff +file. +If it does and is, this preformatted file is (usually) decompressed and then +displayed, via use of a pager. +The pager can be specified in a number of ways, or else will fall back to a +default is used (see option +.B \-P +for details). +If no cat is found or is older than the nroff file, the nroff is filtered +through various programs and is shown immediately. + +If a cat file can be produced (a relative cat directory exists and has +appropriate permissions), +.B %man% +will compress and store the cat file in the background. + +The filters are deciphered by a number of means. +Firstly, the command line option +.B \-p +or the environment variable +.RB $ MANROFFSEQ +is interrogated. +If +.B \-p +was not used and the environment variable was not set, the initial line of +the nroff file is parsed for a preprocessor string. +To contain a valid preprocessor string, the first line must resemble + +.B '\e" +.RB < string > + +where +.B string +can be any combination of letters described by option +.B \-p +below. + +If none of the above methods provide any filter information, a default set +is used. + +A formatting pipeline is formed from the filters and the primary +formatter +.RB ( nroff +or +.RB [ tg ] roff +with +.BR \-t ) +and executed. +Alternatively, if an executable program +.I mandb_nfmt +(or +.I mandb_tfmt +with +.BR \-t ) +exists in the man tree root, it is executed instead. +It gets passed the manual source file, the preprocessor string, and +optionally the device specified with +.BR \-T " or " \-E +as arguments. +.\" ******************************************************************** +.SH OPTIONS +Non argument options that are duplicated either on the command line, in +.RB $ MANOPT , +or both, are not harmful. +For options that require an argument, each duplication will override the +previous argument value. +.SS "General options" +.TP +.BI \-C\ file \fR,\ \fB\-\-config\-file= file +Use this user configuration file rather than the default of +.IR ~/.manpath . +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-D ", " \-\-default +This option is normally issued as the very first option and resets +.B %man%'s +behaviour to its default. +Its use is to reset those options that may have been set in +.RB $ MANOPT . +Any options that follow +.B \-D +will have their usual effect. +.TP +\fB\-\-warnings\fP[=\fIwarnings\/\fP] +Enable warnings from +.IR groff . +This may be used to perform sanity checks on the source text of manual +pages. +.I warnings +is a comma-separated list of warning names; if it is not supplied, the +default is "mac". +See the \(lqWarnings\(rq node in +.B info groff +for a list of available warning names. +.SS "Main modes of operation" +.TP +.if !'po4a'hide' .BR \-f ", " \-\-whatis +Equivalent to +.BR %whatis% . +Display a short description from the manual page, if available. +See +.BR %whatis% (1) +for details. +.TP +.if !'po4a'hide' .BR \-k ", " \-\-apropos +Equivalent to +.BR %apropos% . +Search the short manual page descriptions for keywords and display any +matches. +See +.BR %apropos% (1) +for details. +.TP +.if !'po4a'hide' .BR \-K ", " \-\-global\-apropos +Search for text in all manual pages. +This is a brute-force search, and is likely to take some time; if you can, +you should specify a section to reduce the number of pages that need to be +searched. +Search terms may be simple strings (the default), or regular expressions if +the +.B \-\-regex +option is used. +.IP +Note that this searches the +.I sources +of the manual pages, not the rendered text, and so may include false +positives due to things like comments in source files. +Searching the rendered text would be much slower. +.TP +.if !'po4a'hide' .BR \-l ", " \-\-local\-file +Activate `local' mode. +Format and display local manual files instead of searching through the +system's manual collection. +Each manual page argument will be interpreted as an nroff source file in the +correct format. +.\" Compressed nroff source files with a supported compression +.\" extension will be decompressed by man prior to being displaying via the +.\" usual filters. +No cat file is produced. +If '\-' is listed as one of the arguments, input will be taken from stdin. +When this option is not used, and man fails to find the page required, +before displaying the error message, it attempts to act as if this +option was supplied, using the name as a filename and looking for an +exact match. +.TP +.if !'po4a'hide' .BR \-w ", " \-\-where ", " \-\-path ", " \-\-location +Don't actually display the manual pages, but do print the location(s) of +the source nroff files that would be formatted. +.TP +.if !'po4a'hide' .BR \-W ", " \-\-where\-cat ", " \-\-location\-cat +Don't actually display the manual pages, but do print the location(s) of +the cat files that would be displayed. +If \-w and \-W are both specified, print both separated by a space. +.TP +.if !'po4a'hide' .BR \-c ", " \-\-catman +This option is not for general use and should only be used by the +.B %catman% +program. +.TP +.BI \-R\ encoding\fR,\ \fI \-\-recode\fR=\fIencoding +Instead of formatting the manual page in the usual way, output its source +converted to the specified +.IR encoding . +If you already know the encoding of the source file, you can also use +.BR %manconv% (1) +directly. +However, this option allows you to convert several manual pages to a single +encoding without having to explicitly state the encoding of each, provided +that they were already installed in a structure similar to a manual page +hierarchy. +.SS "Finding manual pages" +.TP +.BI \-L\ locale \fR,\ \fB\-\-locale= locale +.B %program% +will normally determine your current locale by a call to the C function +.BR setlocale (3) +which interrogates various environment variables, possibly including +.RB $ LC_MESSAGES +and +.RB $ LANG . +To temporarily override the determined value, use this option to supply a +.I locale +string directly to +.BR %program% . +Note that it will not take effect until the search for pages actually +begins. +Output such as the help message will always be displayed in the initially +determined locale. +.\" +.\" Due to the rather silly limit of 6 args per request in some `native' +.\" *roff compilers, we have do the following to get the two-line +.\" hanging tag on one line. .PP to begin a new paragraph, then the +.\" tag, then .RS (start relative indent), the text, finally .RE +.\" (end relative indent). +.\" +.PP +.B \-m +.I system\c +\|[\|,.\|.\|.\|]\|, +.BI \-\-systems= system\c +\|[\|,.\|.\|.\|] +.RS +If this system has access to other operating system's manual pages, they can +be accessed using this option. +To search for a manual page from NewOS's manual page collection, +use the option +.B \-m +.BR NewOS . + +The +.I system +specified can be a combination of comma delimited operating system names. +To include a search of the native operating system's manual pages, +include the system name +.B man +in the argument string. +This option will override the +.RB $ SYSTEM +environment variable. +.RE +.TP +.BI \-M\ path \fR,\ \fB\-\-manpath= path +Specify an alternate manpath to use. +By default, +.B %man% +uses +.B %manpath% +derived code to determine the path to search. +This option overrides the +.RB $ MANPATH +environment variable and causes option +.B \-m +to be ignored. + +A path specified as a manpath must be the root of a manual page hierarchy +structured into sections as described in the man-db manual (under "The +manual page system"). +To view manual pages outside such hierarchies, see the +.B \-l +option. +.TP +.BI \-S\ list \fR,\ \fB\-s\ list \fR,\ \fB\-\-sections= list +List is a colon- or comma-separated list of `order specific' manual sections +to search. +This option overrides the +.RB $ MANSECT +environment variable. +(The +.B \-s +spelling is for compatibility with System V.) +.TP +.BI \-e\ sub-extension \fR,\ \fB\-\-extension= sub-extension +Some systems incorporate large packages of manual pages, such as those that +accompany the +.B Tcl +package, into the main manual page hierarchy. +To get around the problem of having two manual pages with the same name +such as +.BR exit (3), +the +.B Tcl +pages were usually all assigned to section +.BR l . +As this is unfortunate, it is now possible to put the pages in the correct +section, and to assign a specific `extension' to them, in this case, +.BR exit (3tcl). +Under normal operation, +.B %man% +will display +.BR exit (3) +in preference to +.BR exit (3tcl). +To negotiate this situation and to avoid having to know which section the +page you require resides in, it is now possible to give +.B %man% +a +.I sub-extension +string indicating which package the page must belong to. +Using the above example, supplying the option +.B \-e\ tcl +to +.B %man% +will restrict the search to pages having an extension of +.BR *tcl . +.TP +.if !'po4a'hide' .BR \-i ", " \-\-ignore\-case +Ignore case when searching for manual pages. +This is the default. +.TP +.if !'po4a'hide' .BR \-I ", " \-\-match\-case +Search for manual pages case-sensitively. +.TP +.if !'po4a'hide' .B \-\-regex +Show all pages with any part of either their names or their descriptions +matching each +.I page +argument as a regular expression, as with +.BR apropos (1). +Since there is usually no reasonable way to pick a "best" page when +searching for a regular expression, this option implies +.BR \-a . +.TP +.if !'po4a'hide' .B \-\-wildcard +Show all pages with any part of either their names or their descriptions +matching each +.I page +argument using shell-style wildcards, as with +.BR apropos (1) +.BR \-\-wildcard . +The +.I page +argument must match the entire name or description, or match on word +boundaries in the description. +Since there is usually no reasonable way to pick a "best" page when +searching for a wildcard, this option implies +.BR \-a . +.TP +.if !'po4a'hide' .B \-\-names\-only +If the +.B \-\-regex +or +.B \-\-wildcard +option is used, match only page names, not page descriptions, as with +.BR whatis (1). +Otherwise, no effect. +.TP +.if !'po4a'hide' .BR \-a ", " \-\-all +By default, +.B %man% +will exit after displaying the most suitable manual page it finds. +Using this option forces +.B %man% +to display all the manual pages with names that match the search criteria. +.TP +.if !'po4a'hide' .BR \-u ", " \-\-update +This option causes +.B %man% +to perform an `inode level' consistency check on its database caches to +ensure that they are an accurate representation of the filesystem. +It will only have a useful effect if +.B %man% +is installed with the setuid bit set. +.TP +.if !'po4a'hide' .B \-\-no\-subpages +By default, +.B %man% +will try to interpret pairs of manual page names given on the command line +as equivalent to a single manual page name containing a hyphen or an +underscore. +This supports the common pattern of programs that implement a number of +subcommands, allowing them to provide manual pages for each that can be +accessed using similar syntax as would be used to invoke the subcommands +themselves. +For example: + +.nf +.if !'po4a'hide' \& $ man \-aw git diff +.if !'po4a'hide' \& /usr/share/man/man1/git\-diff.1.gz +.fi + +To disable this behaviour, use the +.B \-\-no\-subpages +option. + +.nf +.if !'po4a'hide' \& $ man \-aw \-\-no\-subpages git diff +.if !'po4a'hide' \& /usr/share/man/man1/git.1.gz +.if !'po4a'hide' \& /usr/share/man/man3/Git.3pm.gz +.if !'po4a'hide' \& /usr/share/man/man1/diff.1.gz +.fi +.SS "Controlling formatted output" +.TP +.BI \-P\ pager \fR,\ \fB\-\-pager= pager +Specify which output pager to use. +By default, +.B %man% +uses +.BR "%pager%" , +falling back to +.B %cat% +if +.B %pager% +is not found or is not executable. +This option overrides the +.RB $ MANPAGER +environment variable, which in turn overrides the +.RB $ PAGER +environment variable. +It is not used in conjunction with +.B \-f +or +.BR \-k . + +The value may be a simple command name or a command with arguments, and may +use shell quoting (backslashes, single quotes, or double quotes). +It may not use pipes to connect multiple commands; if you need that, use a +wrapper script, which may take the file to display either as an argument or +on standard input. +.TP +.BI \-r\ prompt \fR,\ \fB\-\-prompt= prompt +If a recent version of +.B less +is used as the pager, +.B %man% +will attempt to set its prompt and some sensible options. +The default prompt looks like + +.B \ Manual page\c +.IB \ name ( sec )\c +.BI \ line \ x + +where +.I name +denotes the manual page name, +.I sec +denotes the section it was found under and +.IR x +the current line number. +.\"The default options are +.\".BR \-six8 . +This is achieved by using the +.RB $ LESS +environment variable. +.\"The actual default will depend on your chosen +.\".BR locale . + +Supplying +.B \-r +with a string will override this default. +.\"You may need to do this if your +.\"version of +.\".B less +.\"rejects the default options or if you prefer a different prompt. +The string may contain the text +.B $MAN_PN +which will be expanded to the name of the current manual page and its +section name surrounded by `(' and `)'. +The string used to produce the default could be expressed as + +.B \e\ Manual\e\ page\e\ \e$MAN_PN\e\ ?ltline\e\ %lt?L/%L.: +.br +.B byte\e\ %bB?s/%s..?\e\ (END):?pB\e\ %pB\e\e%.. +.br +.B (press h for help or q to quit) + +It is broken into three lines here for the sake of readability only. +For its meaning see the +.BR less (1) +manual page. +The prompt string is first evaluated by the shell. +All double quotes, back-quotes and backslashes in the prompt must be escaped +by a preceding backslash. +The prompt string may end in an escaped $ which may be followed by further +options for less. +By default +.B %man% +sets the +.B \-ix8 +options. + +The +.RB $ MANLESS +environment variable described below may be used to set a default prompt +string if none is supplied on the command line. +.TP +.if !'po4a'hide' .BR \-7 ", " \-\-ascii +When viewing a pure +.IR ascii (7) +manual page on a 7 bit terminal or terminal emulator, some characters may +not display correctly when using the +.IR latin1 (7) +device description with +.B GNU +.BR nroff . +This option allows pure +.I ascii +manual pages to be displayed in +.I ascii +with the +.I latin1 +device. +It will not translate any +.I latin1 +text. +The following table shows the translations performed: some parts of it may +only be displayed properly when using +.B GNU +.BR nroff 's +.IR latin1 (7) +device. + +.ie c \[shc] \ +. ds softhyphen \[shc] +.el \ +. ds softhyphen \(hy +.na +.TS +tab (@); +l c c c. +Description@Octal@latin1@ascii +_ +T{ +continuation hyphen +T}@255@\*[softhyphen]@- +T{ +bullet (middle dot) +T}@267@\(bu@o +T{ +acute accent +T}@264@\(aa@' +T{ +multiplication sign +T}@327@\(mu@x +.TE +.ad + +If the +.I latin1 +column displays correctly, your terminal may be set up for +.I latin1 +characters and this option is not necessary. +If the +.I latin1 +and +.I ascii +columns are identical, you are reading this page using this option or +.B %man% +did not format this page using the +.I latin1 +device description. +If the +.I latin1 +column is missing or corrupt, you may need to view manual pages with this +option. + +This option is ignored when using options +.BR \-t , +.BR \-H , +.BR \-T , +or +.B \-Z +and may be useless for +.B nroff +other than +.BR GNU's . +.TP +.BI \-E\ encoding\fR,\ \fI \-\-encoding\fR=\fIencoding +Generate output for a character encoding other than the default. +For backward compatibility, +.I encoding +may be an +.B nroff +device such as +.BR ascii ", " latin1 ", or " utf8 +as well as a true character encoding such as +.BR UTF\-8 . +.TP +.if !'po4a'hide' .BR \-\-no\-hyphenation ", " \-\-nh +Normally, +.B nroff +will automatically hyphenate text at line breaks even in words that do not +contain hyphens, if it is necessary to do so to lay out words on a line +without excessive spacing. +This option disables automatic hyphenation, so words will only be hyphenated +if they already contain hyphens. + +If you are writing a manual page and simply want to prevent +.B nroff +from hyphenating a word at an inappropriate point, do not use this option, +but consult the +.B nroff +documentation instead; for instance, you can put "\e%" inside a word to +indicate that it may be hyphenated at that point, or put "\e%" at the start +of a word to prevent it from being hyphenated. +.TP +.if !'po4a'hide' .BR \-\-no\-justification ", " \-\-nj +Normally, +.B nroff +will automatically justify text to both margins. +This option disables full justification, leaving justified only to the left +margin, sometimes called "ragged-right" text. + +If you are writing a manual page and simply want to prevent +.B nroff +from justifying certain paragraphs, do not use this option, but consult the +.B nroff +documentation instead; for instance, you can use the ".na", ".nf", ".fi", +and ".ad" requests to temporarily disable adjusting and filling. +.TP +.BI \-p\ string \fR,\ \fB\-\-preprocessor= string +Specify the sequence of preprocessors to run before +.B nroff +or +.BR troff / groff . +Not all installations will have a full set of preprocessors. +Some of the preprocessors and the letters used to designate them are: +.BR eqn " (" e ), +.BR grap " (" g ), +.BR pic " (" p ), +.BR tbl " (" t ), +.BR vgrind " (" v ), +.BR refer " (" r ). +This option overrides the +.RB $ MANROFFSEQ +environment variable. +.B %zsoelim% +is always run as the very first preprocessor. +.TP +.if !'po4a'hide' .BR \-t ", " \-\-troff +Use +.I %troff% +to format the manual page to stdout. +This option is not required in conjunction with +.BR \-H , +.BR \-T , +or +.BR \-Z . +.TP +\fB\-T\fP[\fIdevice\/\fP], \fB\-\-troff\-device\fP[=\fIdevice\/\fP] +This option is used to change +.B groff +(or possibly +.BR troff's ) +output to be suitable for a device other than the default. +It implies +.BR \-t . +Examples (provided with Groff-1.17) include +.BR dvi ", " latin1 ", " ps ", " utf8 , +.BR X75 " and " X100 . +.TP +\fB\-H\fP[\fIbrowser\/\fP], \fB\-\-html\fP[=\fIbrowser\/\fP] +This option will cause +.B groff +to produce HTML output, and will display that output in a web browser. +The choice of browser is determined by the optional +.I browser +argument if one is provided, by the +.RB $ BROWSER +environment variable, or by a compile-time default if that is unset (usually +.BR lynx ). +This option implies +.BR \-t , +and will only work with +.B GNU +.BR troff . +.TP +\fB\-X\fP[\fIdpi\/\fP], \fB\-\-gxditview\fP[=\fIdpi\/\fP] +This option displays the output of +.B groff +in a graphical window using the +.B gxditview +program. +The +.I dpi +(dots per inch) may be 75, 75-12, 100, or 100-12, defaulting to 75; +the -12 variants use a 12-point base font. +This option implies +.B \-T +with the X75, X75-12, X100, or X100-12 device respectively. +.TP +.if !'po4a'hide' .BR \-Z ", " \-\-ditroff +.B groff +will run +.B troff +and then use an appropriate post-processor to produce output suitable for +the chosen device. +If +.I %troff% +is +.BR groff , +this option is passed to +.B groff +and will suppress the use of a post-processor. +It implies +.BR \-t . +.SS "Getting help" +.TP +.if !'po4a'hide' .BR \-? ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-\-usage +Print a short usage message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "EXIT STATUS" +.TP +.if !'po4a'hide' .B 0 +Successful program execution. +.TP +.if !'po4a'hide' .B 1 +Usage, syntax or configuration file error. +.TP +.if !'po4a'hide' .B 2 +Operational error. +.TP +.if !'po4a'hide' .B 3 +A child process returned a non-zero exit status. +.TP +.if !'po4a'hide' .B 16 +At least one of the pages/files/keywords didn't exist or wasn't matched. +.SH ENVIRONMENT +.\".TP \w'MANROFFSEQ\ \ 'u +.TP +.if !'po4a'hide' .B MANPATH +If +.RB $ MANPATH +is set, its value is used as the path to search for manual pages. +.TP +.if !'po4a'hide' .B MANROFFOPT +The contents of +.RB $ MANROFFOPT +are added to the command line every time +.B man +invokes the formatter +.RB ( nroff , +.BR troff , +or +.BR groff ). +.TP +.if !'po4a'hide' .B MANROFFSEQ +If +.RB $ MANROFFSEQ +is set, its value is used to determine the set of preprocessors to pass +each manual page through. +The default preprocessor list is system dependent. +.TP +.if !'po4a'hide' .B MANSECT +If +.RB $ MANSECT +is set, its value is a colon-delimited list of sections and it is used to +determine which manual sections to search and in what order. +The default is "%sections%", unless overridden by the +.B SECTION +directive in +.IR %manpath_config_file% . +.TP +.if !'po4a'hide' .BR MANPAGER , " PAGER" +If +.RB $ MANPAGER +or +.RB $ PAGER +is set +.RB ($ MANPAGER +is used in preference), its value is used as the name of the program used to +display the manual page. +By default, +.B %pager% +is used, falling back to +.B %cat% +if +.B %pager% +is not found or is not executable. + +The value may be a simple command name or a command with arguments, and may +use shell quoting (backslashes, single quotes, or double quotes). +It may not use pipes to connect multiple commands; if you need that, use a +wrapper script, which may take the file to display either as an argument or +on standard input. +.TP +.if !'po4a'hide' .B MANLESS +If +.RB $ MANLESS +is set, its value will be used as the default prompt string for the +.B less +pager, as if it had been passed using the +.B \-r +option (so any occurrences of the text +.B $MAN_PN +will be expanded in the same way). +For example, if you want to set the prompt string unconditionally to +\(lqmy prompt string\(rq, set +.RB $ MANLESS +to +.RB \(oq \-Psmy\ prompt\ string \(cq. +Using the +.B \-r +option overrides this environment variable. +.TP +.if !'po4a'hide' .B BROWSER +If +.RB $ BROWSER +is set, its value is a colon-delimited list of commands, each of which in +turn is used to try to start a web browser for +.B man +.BR \-\-html . +In each command, +.I %s +is replaced by a filename containing the HTML output from +.BR groff , +.I %% +is replaced by a single percent sign (%), and +.I %c +is replaced by a colon (:). +.TP +.if !'po4a'hide' .B SYSTEM +If +.RB $ SYSTEM +is set, it will have the same effect as if it had been specified as the +argument to the +.B \-m +option. +.TP +.if !'po4a'hide' .B MANOPT +If +.RB $ MANOPT +is set, it will be parsed prior to +.B %man%'s +command line and is expected to be in a similar format. +As all of the other +.B %man% +specific environment variables can be expressed as command line options, and +are thus candidates for being included in +.RB $ MANOPT +it is expected that they will become obsolete. +N.B. All spaces that should be interpreted as part of an option's argument +must be escaped. +.TP +.if !'po4a'hide' .B MANWIDTH +If +.RB $ MANWIDTH +is set, its value is used as the line length for which manual pages should +be formatted. +If it is not set, manual pages will be formatted with a line length +appropriate to the current terminal (using the value of +.RB $ COLUMNS , +an +.BR ioctl (2) +if available, or falling back to 80 characters if neither is available). +Cat pages will only be saved when the default formatting can be used, that +is when the terminal line length is between 66 and 80 characters. +.TP +.if !'po4a'hide' .B MAN_KEEP_FORMATTING +Normally, when output is not being directed to a terminal (such as to a file +or a pipe), formatting characters are discarded to make it easier to read +the result without special tools. +However, if +.RB $ MAN_KEEP_FORMATTING +is set to any non-empty value, these formatting characters are retained. +This may be useful for wrappers around +.B %man% +that can interpret formatting characters. +.TP +.if !'po4a'hide' .B MAN_KEEP_STDERR +Normally, when output is being directed to a terminal (usually to a pager), +any error output from the command used to produce formatted versions of +manual pages is discarded to avoid interfering with the pager's display. +Programs such as +.B groff +often produce relatively minor error messages about typographical problems +such as poor alignment, which are unsightly and generally confusing when +displayed along with the manual page. +However, some users want to see them anyway, so, if +.RB $ MAN_KEEP_STDERR +is set to any non-empty value, error output will be displayed as usual. +.TP +.if !'po4a'hide' .BR LANG , " LC_MESSAGES" +Depending on system and implementation, either or both of +.RB $ LANG +and +.RB $ LC_MESSAGES +will be interrogated for the current message locale. +.B %man% +will display its messages in that locale (if available). +See +.BR setlocale (3) +for precise details. +.SH FILES +.TP +.if !'po4a'hide' .I %manpath_config_file% +man-db configuration file. +.TP +.if !'po4a'hide' .I /usr/share/man +A global manual page hierarchy. +.TP +.if !'po4a'hide' .I /usr/share/man/index.(bt|db|dir|pag) +A traditional global +.I index +database cache. +.TP +.if !'po4a'hide' .I /var/cache/man/index.(bt|db|dir|pag) +An FHS +compliant global +.I index +database cache. +.SH "SEE ALSO" +.if !'po4a'hide' .BR %apropos% (1), +.if !'po4a'hide' .BR groff (1), +.if !'po4a'hide' .BR less (1), +.if !'po4a'hide' .BR %manpath% (1), +.if !'po4a'hide' .BR nroff (1), +.if !'po4a'hide' .BR troff (1), +.if !'po4a'hide' .BR %whatis% (1), +.if !'po4a'hide' .BR %zsoelim% (1), +.if !'po4a'hide' .BR setlocale (3), +.if !'po4a'hide' .BR manpath (5), +.if !'po4a'hide' .BR ascii (7), +.if !'po4a'hide' .BR latin1 (7), +.if !'po4a'hide' .BR man (7), +.if !'po4a'hide' .BR %catman% (8), +.if !'po4a'hide' .BR %mandb% (8), +the man-db package manual, +.BR FSSTND +.SH HISTORY +1990, 1991 \(en Originally written by John W.\& Eaton (jwe@che.utexas.edu). + +Dec 23 1992: Rik Faith (faith@cs.unc.edu) applied bug fixes +supplied by Willem Kasdorp (wkasdo@nikhefk.nikef.nl). + +30th April 1994 \(en 23rd February 2000: Wilf. (G.Wilford@ee.surrey.ac.uk) +has been developing and maintaining this package +with the help of a few dedicated people. + +30th October 1996 \(en 30th March 2001: Fabrizio Polacco <fpolacco@debian.org> +maintained and enhanced this package for the Debian project, with the +help of all the community. + +31st March 2001 \(en present day: Colin Watson <cjwatson@debian.org> is now +developing and maintaining man-db. diff --git a/man/man1/manconv.man1 b/man/man1/manconv.man1 new file mode 100644 index 0000000..7731575 --- /dev/null +++ b/man/man1/manconv.man1 @@ -0,0 +1,78 @@ +.\" Man page for manconv +.\" +.\" Copyright (c) 2007, 2008 Colin Watson <cjwatson@debian.org> +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.pc +.TH %thmanconv% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%manconv% \- convert manual page from one encoding to another +.SH SYNOPSIS +.B %manconv% +.B \-f +.IR from-code \|[: from-code \|.\|.\|.] +.B \-t +.I to-code +.RB [\| \-dqhV \|] +.RI [\| filename \|] +.SH DESCRIPTION +.B %manconv% +converts a manual page from one encoding to another, like +.BR iconv . +Unlike +.BR iconv , +it can try multiple possible input encodings in sequence. +This is useful for manual pages installed in directories without an explicit +encoding declaration, since they may be in UTF\-8 or in a legacy character +set. +.PP +If an encoding declaration is found on the first line of the manual page, +that declaration overrides any input encodings specified on +.BR %manconv% 's +command line. +Encoding declarations have the following form: +.PP +.RS +.nf +.if !'po4a'hide' \&\(aq\e" \-*\- coding: UTF\-8 \-*\- +.fi +.RE +.PP +or (if manual page preprocessors are also to be declared): +.PP +.RS +.nf +.if !'po4a'hide' \&\(aq\e" t \-*\- coding: ISO\-8859\-1 \-*\- +.fi +.RE +.SH OPTIONS +.TP +\fB\-f\fP \fIencodings\fP, \fB\-\-from\-code\fP \fIencodings\fP +Try each of +.I encodings +(a colon-separated list) in sequence as the input encoding. +.TP +\fB\-t\fP \fIencoding\fP, \fB\-\-to\-code\fP \fIencoding\fP +Convert the manual page to +.IR encoding . +.TP +.if !'po4a'hide' .BR \-q ", " \-\-quiet +Do not issue error messages when the page cannot be converted. +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-h ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "SEE ALSO" +.if !'po4a'hide' .IR iconv (1), +.if !'po4a'hide' .IR man (1) +.SH AUTHOR +.nf +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi diff --git a/man/man1/manpath.man1 b/man/man1/manpath.man1 new file mode 100644 index 0000000..9b9b840 --- /dev/null +++ b/man/man1/manpath.man1 @@ -0,0 +1,137 @@ +.\" Man page for manpath +.\" +.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the COPYING file that comes with the +.\" man-db distribution. +.\" +.\" Sun Jan 22 22:15:17 GMT 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.pc +.TH %thmanpath% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%manpath% \- determine search path for manual pages +.SH SYNOPSIS +.B %manpath% +.RB [\| \-qgdc?V \|] +.RB [\| \-m +.IR system \|[\|,.\|.\|.\|]\|] +.RB [\| \-C +.IR file \|] +.SH DESCRIPTION +If +.RB $ MANPATH +is set, +.B %manpath% +will simply display its contents and issue a warning. +If not, +.B %manpath% +will determine a suitable manual page hierarchy search path and display the +results. + +The colon-delimited path is determined using information gained from the +man-db configuration file - +.RI ( "%manpath_config_file%" ) +and the user's environment. +.SH OPTIONS +.TP +.if !'po4a'hide' .BR \-q ", " \-\-quiet +Do not issue warnings. +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-c ", " \-\-catpath +Produce a catpath as opposed to a manpath. +Once the manpath is determined, +each path element is converted to its relative catpath. +.TP +.if !'po4a'hide' .BR \-g ", " \-\-global +Produce a manpath consisting of all paths named as `global' within the +man-db configuration file. +.\" +.\" Due to the rather silly limit of 6 args per request in some `native' +.\" *roff compilers, we have do the following to get the two-line +.\" hanging tag on one line. .PP to begin a new paragraph, then the +.\" tag, then .RS (start relative indent), the text, finally .RE +.\" (end relative indent). +.\" +.PP +.B \-m +.I system\c +\|[\|,.\|.\|.\|]\|, +.BI \-\-systems= system\c +\|[\|,.\|.\|.\|] +.RS +If this system has access to other operating system's manual hierarchies, +this option can be used to include them in the output of +.BR %manpath% . +To include NewOS's manual page hierarchies use the option +.B \-m +.BR NewOS . + +The +.I system +specified can be a combination of comma delimited operating system names. +To include the native operating system's manual page hierarchies, +the system name +.B man +must be included in the argument string. +This option will override the +.RB $ SYSTEM +environment variable. +.RE +.TP +.BI \-C\ file \fR,\ \fB\-\-config\-file= file +Use this user configuration file rather than the default of +.IR ~/.manpath . +.TP +.if !'po4a'hide' .BR \-? ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-\-usage +Print a short usage message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH ENVIRONMENT +.TP +.if !'po4a'hide' .B MANPATH +If +.RB $ MANPATH +is set, +.B %manpath% +displays its value rather than determining it on the fly. +If +.RB $ MANPATH +is prefixed by a colon, then the value of the variable is appended +to the list determined from the content of the configuration files. +If the colon comes at the end of the value in the variable, then the +determined list is appended to the content of the variable. +If the value of the variable contains a double colon +.RB ( :: ), +then the determined list is inserted in the middle of the value, between +the two colons. +.TP +.if !'po4a'hide' .B SYSTEM +If +.RB $ SYSTEM +is set, it will have the same effect as if it had been specified as the +argument to the +.B \-m +option. +.SH FILES +.TP \w'%manpath_config_file%'u+2n +.if !'po4a'hide' .I %manpath_config_file% +man-db configuration file. +.SH "SEE ALSO" +.if !'po4a'hide' .BR %apropos% (1), +.if !'po4a'hide' .BR %man% (1), +.if !'po4a'hide' .BR %whatis% (1) +.SH AUTHOR +.nf +.if !'po4a'hide' Wilf. (G.Wilford@ee.surrey.ac.uk). +.if !'po4a'hide' Fabrizio Polacco (fpolacco@debian.org). +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi diff --git a/man/man1/whatis.man1 b/man/man1/whatis.man1 new file mode 100644 index 0000000..83a93e0 --- /dev/null +++ b/man/man1/whatis.man1 @@ -0,0 +1,262 @@ +.\" Man page for whatis +.\" +.\" Copyright (C), 1994, 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.\" +.\" Sat Oct 29 13:09:31 GMT 1994 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.pc +.TH %thwhatis% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%whatis% \- display one-line manual page descriptions +.SH SYNOPSIS +.B %whatis% +.RB [\| \-dlv?V \|] +.RB [\| \-r \||\| \-w\c +\|] +.RB [\| \-s +.IR list \|] +.RB [\| \-m +.IR system \|[\|,.\|.\|.\|]\|] +.RB [\| \-M +.IR path \|] +.RB [\| \-L +.IR locale \|] +.RB [\| \-C +.IR file \|] +.I name +\&.\|.\|. +.SH DESCRIPTION +Each manual page has a short description available within it. +.B %whatis% +searches the manual page names and displays the manual page descriptions +of any +.I name +matched. + +.I name +may contain wildcards +.RB ( \-w ) +or be a regular expression +.RB ( \-r ). +Using these options, it may be necessary to quote the +.I name +or escape (\\) the special characters to stop the shell from interpreting +them. + +.B index +databases are used during the search, and are updated by the +.B %mandb% +program. +Depending on your installation, this may be run by a periodic cron job, or +may need to be run manually after new manual pages have been installed. +To produce an old style text +.B whatis +database from the relative +.B index +database, issue the command: + +.B %whatis% \-M +.I manpath +.B \-w '*' | sort > +.I manpath/whatis + +where +.I manpath +is a manual page hierarchy such as +.IR /usr/man . +.SH OPTIONS +.TP +.if !'po4a'hide' .BR \-d ", " \-\-debug +Print debugging information. +.TP +.if !'po4a'hide' .BR \-v ", " \-\-verbose +Print verbose warning messages. +.TP +.if !'po4a'hide' .BR \-r ", " \-\-regex +Interpret each +.I name +as a regular expression. +If a +.I name +matches any part of a page name, a match will be made. +This option causes +.B %whatis% +to be somewhat slower due to the nature of database searches. +.TP +.if !'po4a'hide' .BR \-w ", " \-\-wildcard +Interpret each +.I name +as a pattern containing shell style wildcards. +For a match to be made, an expanded +.I name +must match the entire page name. +This option causes +.B %whatis% +to be somewhat slower due to the nature of database searches. +.TP +.if !'po4a'hide' .BR \-l ", " \-\-long +Do not trim output to the terminal width. +Normally, output will be truncated to the terminal width to avoid ugly +results from poorly-written +.B NAME +sections. +.TP +\fB\-s\fP \fIlist\fP, \fB\-\-sections\fP \fIlist\fP, \fB\-\-section\fP \fIlist\fP +Search only the given manual sections. +.I list +is a colon- or comma-separated list of sections. +If an entry in +.I list +is a simple section, for example "3", then the displayed list of +descriptions will include pages in sections "3", "3perl", "3x", and so on; +while if an entry in +.I list +has an extension, for example "3perl", then the list will only include +pages in that exact part of the manual section. +.\" +.\" Due to the rather silly limit of 6 args per request in some `native' +.\" *roff compilers, we have do the following to get the two-line +.\" hanging tag on one line. .PP to begin a new paragraph, then the +.\" tag, then .RS (start relative indent), the text, finally .RE +.\" (end relative indent). +.\" +.PP +.B \-m +.I system\c +\|[\|,.\|.\|.\|]\|, +.BI \-\-systems= system\c +\|[\|,.\|.\|.\|] +.RS +If this system has access to other operating system's manual page names, +they can be accessed using this option. +To search NewOS's manual page names, +use the option +.B \-m +.BR NewOS . + +The +.I system +specified can be a combination of comma delimited operating system names. +To include a search of the native operating system's +manual page names, include the system name +.B man +in the argument string. +This option will override the +.RB $ SYSTEM +environment variable. +.RE +.TP +.BI \-M\ path \fR,\ \fB\-\-manpath= path +Specify an alternate set of colon-delimited manual page hierarchies to +search. +By default, +.B %program% +uses the +.RB $ MANPATH +environment variable, unless it is empty or unset, in which case it will +determine an appropriate manpath based on your +.RB $ PATH +environment variable. +This option overrides the contents of +.RB $ MANPATH . +.TP +.BI \-L\ locale \fR,\ \fB\-\-locale= locale +.B %program% +will normally determine your current locale by a call to the C function +.BR setlocale (3) +which interrogates various environment variables, possibly including +.RB $ LC_MESSAGES +and +.RB $ LANG . +To temporarily override the determined value, use this option to supply a +.I locale +string directly to +.BR %program% . +Note that it will not take effect until the search for pages actually +begins. +Output such as the help message will always be displayed in the initially +determined locale. +.TP +.BI \-C\ file \fR,\ \fB\-\-config\-file= file +Use this user configuration file rather than the default of +.IR ~/.manpath . +.TP +.if !'po4a'hide' .BR \-? ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-\-usage +Print a short usage message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "EXIT STATUS" +.TP +.if !'po4a'hide' .B 0 +Successful program execution. +.TP +.if !'po4a'hide' .B 1 +Usage, syntax or configuration file error. +.TP +.if !'po4a'hide' .B 2 +Operational error. +.TP +.if !'po4a'hide' .B 16 +Nothing was found that matched the criteria specified. +.SH ENVIRONMENT +.TP +.if !'po4a'hide' .B SYSTEM +If +.RB $ SYSTEM +is set, it will have the same effect as if it had been specified as the +argument to the +.B \-m +option. +.TP +.if !'po4a'hide' .B MANPATH +If +.RB $ MANPATH +is set, its value is interpreted as the colon-delimited manual page +hierarchy search path to use. +.TP +.if !'po4a'hide' .B MANWIDTH +If +.RB $ MANWIDTH +is set, its value is used as the terminal width (see the +.B \-\-long +option). +If it is not set, the terminal width will be calculated using the value of +.RB $ COLUMNS , +an +.BR ioctl (2) +if available, or falling back to 80 characters if all else fails. +.SH FILES +.TP +.if !'po4a'hide' .I /usr/share/man/index.(bt|db|dir|pag) +A traditional global +.I index +database cache. +.TP +.if !'po4a'hide' .I /var/cache/man/index.(bt|db|dir|pag) +An FHS +compliant global +.I index +database cache. +.TP +.if !'po4a'hide' .I /usr/share/man/\|.\|.\|.\|/whatis +A traditional +.B whatis +text database. +.SH "SEE ALSO" +.if !'po4a'hide' .BR %apropos% (1), +.if !'po4a'hide' .BR %man% (1), +.if !'po4a'hide' .BR %mandb% (8) +.SH AUTHOR +.nf +.if !'po4a'hide' Wilf. (G.Wilford@ee.surrey.ac.uk). +.if !'po4a'hide' Fabrizio Polacco (fpolacco@debian.org). +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi diff --git a/man/man1/zsoelim.man1 b/man/man1/zsoelim.man1 new file mode 100644 index 0000000..0915a3a --- /dev/null +++ b/man/man1/zsoelim.man1 @@ -0,0 +1,80 @@ +.\" Man page for %zsoelim% +.\" +.\" Copyright (C), 1994, 1995, Graeme W. Wilford. (Wilf.) +.\" +.\" You may distribute under the terms of the GNU General Public +.\" License as specified in the file COPYING that comes with the +.\" man-db distribution. +.\" +.\" Sat Dec 10 19:33:32 GMT 1994 Wilf. (G.Wilford@ee.surrey.ac.uk) +.\" +.pc +.TH %thzsoelim% 1 "%date%" "%version%" "Manual pager utils" +.SH NAME +%zsoelim% \- satisfy .so requests in roff input +.SH SYNOPSIS +.B %zsoelim% +.RB [\| \-CVh \|] +.RI [\| file +\&.\|.\|.\|] +.SH DESCRIPTION +.B %zsoelim% +parses +.I file +arguments, or if none are specified, its standard input for lines of the +form: + +.B .so +.RI <\| filename \|> + +These requests are replaced by the contents of the +.I filename +specified. +If the request cannot be met, +.B %zsoelim% +looks for +.I filename.ext +where +.I .ext +can be one of +.BR .gz , +.BR .Z +or +.BR .z . +Other extension types may be supported depending upon compile time options. +If the request can be met by a compressed file, this file is decompressed +using an appropriate decompressor and its output is used to satisfy +the request. + +Traditionally, +.B soelim +programs were used to allow roff preprocessors to be able to preprocess the +files referred to by the requests. +This particular version was written to circumvent problems created by +support for compressed manual pages. +.SH OPTIONS +.TP +.if !'po4a'hide' .BR \-C ", " \-\-compatible +This flag is available for compatibility with other +.B soelim +programs. +Its use is to enable .so requests followed by something other than +whitespace. +As this is already the default behaviour, it is ignored. +.TP +.if !'po4a'hide' .BR \-h ", " \-\-help +Print a help message and exit. +.TP +.if !'po4a'hide' .BR \-V ", " \-\-version +Display version information. +.SH "SEE ALSO" +.if !'po4a'hide' .BR groff (1), +.if !'po4a'hide' .BR %man% (1), +.if !'po4a'hide' .BR nroff (1), +.if !'po4a'hide' .BR troff (1) +.SH AUTHOR +.nf +.if !'po4a'hide' Wilf. (G.Wilford@ee.surrey.ac.uk). +.if !'po4a'hide' Fabrizio Polacco (fpolacco@debian.org). +.if !'po4a'hide' Colin Watson (cjwatson@debian.org). +.fi |