Adding upstream version 2.8.5.upstream/2.8.5upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1418 insertions, 0 deletions

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.