Revamp man(1) to be a more accessible introduction

Fixes Savannah bug #53050.

* man/man1/man.man1 (SYNOPSIS): Delete details of most options, as it
had got much too long and indigestible.  The OPTIONS section below
remains, and is better-organised and easier to read.  Delete the "man
-c" form entirely, as it's only for internal use by catman.
(DESCRIPTION): Move list of default sections to ...
(DEFAULTS): ... here.
(EXAMPLES): Use a real example rather than the peculiar "alias"
terminology for "man -t".
(OVERVIEW): Various minor editorial improvements.  Remove discussion of
index database caches: it's mostly irrelevant to users, and is already
better-documented in mandb(8), apropos(1), and whatis(1).  Simplify
discussion of where pages are stored.  Briefly describe what cat pages
are.  Rewrite description of localisation support to read more fluently
and to take into account that most users will already have a suitable
locale set up.  Drop discussion of translations of this package's own
messages: this should be standard rather than something that we
explicitly need to call out here, and the term "message catalogues" was
opaque.
(DEFAULTS): Remove discussion of index database caches, as above.
Remove discussion of cat pages, since this is an implementation detail
and confused matters here too much.
(Finding manual pages): Tighten up language in description of
--sections.  Simplify description of --update, and tell readers that it
is normally better to run mandb(8) instead.
(FILES): Remove mention of index database caches from here.  While
man(1) does use them, they're an implementation detail and are
better-documented elsewhere.
(SEE ALSO): Remove overly-detailed cross-references to setlocale(3),
ascii(7), latin1(7), the man-db manual, and the FSSTND.  Add a paragraph
mentioning documentation in other formats, such as info(1) or HTML.
* man/man5/manpath.man5 (FORMAT): Remove stray quote before the FSSTND
keyword.
* man/man8/mandb.man8 (DESCRIPTION): Remove claim that index database
caches are usually maintained by man(1).

* man/man1/man.man1, man/man1/manpath.man1: Use the "..." style of
quoting rather than the `...' style.

4 files changed, 77 insertions, 256 deletions

diff --git a/man/man1/man.man1 b/man/man1/man.man1
index 1706a342..78d66d7a 100644
--- a/man/man1/man.man1
+++ b/man/man1/man.man1
@@ -3,7 +3,7 @@
 .\" Man page for man
 .\"
 .\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.)
-.\" Copyright (C) 2001, 2002, 2003, 2006, 2007, 2008 Colin Watson.
+.\" Copyright (C) 2001-2019 Colin Watson.
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -18,68 +18,21 @@
 .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 [\| "man options" \|]
 .RI [\|[\| section \|]
 .IR page [.\| section \|]\ \|.\|.\|.\|]\ \.\|.\|.\&
 .\" The apropos command line
 .br
 .B %man%
 .B \-k
-.RI [\| apropos
-.IR options \|]
+.RI [\| "apropos 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 [\| "man options" \|]
 .RI [\| section \|]
 .IR term \ .\|.\|.\&
 .\" The whatis command line
@@ -94,59 +47,16 @@
 .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 \|]
+.RI [\| "man options" \|]
 .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 \|]
+.RI [\| "man options" \|]
 .I page
 \&.\|.\|.\&
-.\" --help and --version
-.br
-.B %man%
-.RB [\| \-?V \|]
 .SH DESCRIPTION
 .B %man%
 is the system's manual pager.
@@ -167,12 +77,8 @@ to look only in that
 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% ),
+following a pre-defined order (see
+.BR DEFAULTS ),
 and to show only the first
 .I page
 found, even if
@@ -298,10 +204,10 @@ Display, in succession, all of the available
 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
+\fB%man% \-t \fIbash \fR|\fI lpr \-Pps
+Format the manual page for
+.I bash
+into the default
 .B troff
 or
 .B groff
@@ -355,9 +261,9 @@ 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
+It is possible to set the "catch-all" variable
 .RB $ MANOPT
-to any string in command line format with the exception that any spaces
+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%
@@ -370,85 +276,31 @@ 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
+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.
+Manual pages are normally stored in
+.BR nroff (1)
+format under a directory such as
+.IR /usr/share/man .
+In some installations, there may also be preformatted
+.I cat pages
+to improve performance.
+See
+.BR manpath (5)
+for details of where these files are stored.
 
-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
+This package supports manual pages in multiple languages, controlled by your
+.IR locale .
+If your system did not set this up for you automatically, then you may need
+to set
 .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:
+.RB $ LANG ,
+or another system-dependent environment variable to indicate your preferred
+locale, usually specified in the
+.B POSIX
+format:
 
 .\"
 .\" Need a \c to make sure we don't get a space where we don't want one
@@ -466,53 +318,32 @@ If the desired page is available in your
 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.
+If you find that the translations 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.
+The order of sections to search may be overridden by the environment
+variable
+.RB $ MANSECT
+or by the
+.B SECTION
+directive in
+.IR %manpath_config_file% .
+By default it is as follows:
 
-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
+.RS
+.if !'po4a'hide' %sections%
+.RE
+
+The formatted manual page is displayed using a
+.IR pager .
+This can be specified in a number of ways, or else will fall back to a
 default (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
@@ -630,7 +461,7 @@ 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.
+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
@@ -732,8 +563,10 @@ option.
 \fB\-S\fR \fIlist\/\fR, \
 \fB\-s\fR \fIlist\/\fR, \
 \fB\-\-sections=\fIlist\/\fR
-List is a colon- or comma-separated list of `order specific' manual sections
-to search.
+The given
+.I list
+is a colon- or comma-separated list of sections, used to determine which
+manual sections to search and in what order.
 This option overrides the
 .RB $ MANSECT
 environment variable.
@@ -754,7 +587,7 @@ the
 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,
+section, and to assign a specific "extension" to them, in this case,
 .BR exit (3tcl).
 Under normal operation,
 .B %man%
@@ -827,11 +660,10 @@ to display all the manual pages with names that match the search criteria.
 .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.
+to update its database caches of installed manual pages.
+This is only needed in rare situations, and it is normally better to run
+.BR %mandb% (8)
+instead.
 .TP
 .if !'po4a'hide' .B \-\-no\-subpages
 By default,
@@ -926,7 +758,7 @@ with a string will override this default.
 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 `)'.
+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.:
@@ -1367,17 +1199,6 @@ 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),
@@ -1387,15 +1208,14 @@ database cache.
 .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,
-.B FSSTND
+.if !'po4a'hide' .BR %mandb% (8)
+.PP
+Documentation for some packages may be available in other formats, such as
+.BR info (1)
+or HTML.
 .SH HISTORY
 1990, 1991 \(en Originally written by John W.\& Eaton (jwe@che.utexas.edu).
 
diff --git a/man/man1/manpath.man1 b/man/man1/manpath.man1
index d4386adc..3b5165f9 100644
--- a/man/man1/manpath.man1
+++ b/man/man1/manpath.man1
@@ -1,6 +1,7 @@
 .\" Man page for manpath
 .\"
-.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (C) 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (C) 2001-2019 Colin Watson.
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the COPYING file that comes with the
@@ -48,7 +49,7 @@ 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
+Produce a manpath consisting of all paths named as "global" within the
 man-db configuration file.
 .TP
 \fB\-m\fR \fIsystem\fR\|[\|,.\|.\|.\|]\|, \
diff --git a/man/man5/manpath.man5 b/man/man5/manpath.man5
index 5b29356a..04d77a4b 100644
--- a/man/man5/manpath.man5
+++ b/man/man5/manpath.man5
@@ -1,7 +1,7 @@
 .\" Man page for format of the manpath.config data file
 .\"
 .\" Copyright (C) 1994, 1995 Graeme W. Wilford. (Wilf.)
-.\" Copyright (C) 2001, 2007, 2008 Colin Watson.
+.\" Copyright (C) 2001-2019 Colin Watson.
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -82,7 +82,7 @@ directory hierarchy for their storage.
 To observe the
 .B Linux FSSTND
 the keyword
-.RB ` FSSTND
+.B FSSTND
 can be used in place of an actual directory.
 
 Unfortunately, it is necessary to specify
diff --git a/man/man8/mandb.man8 b/man/man8/mandb.man8
index ce2a77b0..84ab3e69 100644
--- a/man/man8/mandb.man8
+++ b/man/man8/mandb.man8
@@ -1,7 +1,8 @@
 '\" t
 .\" Man page for mandb
 .\"
-.\" Copyright (C), 1994, 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (C) 1994, 1995, Graeme W. Wilford. (Wilf.)
+.\" Copyright (C) 2001-2019 Colin Watson.
 .\"
 .\" You may distribute under the terms of the GNU General Public
 .\" License as specified in the file COPYING that comes with the
@@ -30,8 +31,7 @@
 .B %mandb%
 is used to initialise or manually update
 .B index
-database caches that are usually maintained by
-.BR %man% .
+database caches.
 The caches contain information relevant to the current state of the manual
 page system and the information stored within them is used by the man-db
 utilities to enhance their speed and functionality.