Improve documentation of search path handling

Fixes Savannah bug #61862.

* man/man5/manpath.man5 (SEARCH PATH): New section.
* man/man1/apropos.man1 (ENVIRONMENT): Refer to manpath(5) for details
of MANPATH.
* man/man1/man.man1 (ENVIRONMENT): Likewise.
* man/man1/manpath.man1 (ENVIRONMENT): Likewise.
* man/man1/whatis.man1 (ENVIRONMENT): Likewise.
* man/man8/catman.man8 (ENVIRONMENT): Likewise.

6 files changed, 105 insertions, 10 deletions

diff --git a/man/man1/apropos.man1 b/man/man1/apropos.man1
index a5eeb323..c8dce1d6 100644
--- a/man/man1/apropos.man1
+++ b/man/man1/apropos.man1
@@ -207,6 +207,13 @@ If
 .RB $ MANPATH
 is set, its value is interpreted as the colon-delimited manual page
 hierarchy search path to use.
+
+See the
+.B SEARCH PATH
+section of
+.BR manpath (5)
+for the default behaviour and details of how this environment variable is
+handled.
 .TP
 .if !'po4a'hide' .B MANWIDTH
 If
diff --git a/man/man1/man.man1 b/man/man1/man.man1
index 1852dbe0..46070a33 100644
--- a/man/man1/man.man1
+++ b/man/man1/man.man1
@@ -1068,6 +1068,13 @@ At least one of the pages/files/keywords didn't exist or wasn't matched.
 If
 .RB $ MANPATH
 is set, its value is used as the path to search for manual pages.
+
+See the
+.B SEARCH PATH
+section of
+.BR manpath (5)
+for the default behaviour and details of how this environment variable is
+handled.
 .TP
 .if !'po4a'hide' .B MANROFFOPT
 Every time
diff --git a/man/man1/manpath.man1 b/man/man1/manpath.man1
index 0d232083..54f8425b 100644
--- a/man/man1/manpath.man1
+++ b/man/man1/manpath.man1
@@ -92,16 +92,13 @@ If
 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.
+
+See the
+.B SEARCH PATH
+section of
+.BR manpath (5)
+for the default behaviour and details of how this environment variable is
+handled.
 .TP
 .if !'po4a'hide' .B SYSTEM
 If
diff --git a/man/man1/whatis.man1 b/man/man1/whatis.man1
index d0107585..ce6aa5dd 100644
--- a/man/man1/whatis.man1
+++ b/man/man1/whatis.man1
@@ -211,6 +211,13 @@ If
 .RB $ MANPATH
 is set, its value is interpreted as the colon-delimited manual page
 hierarchy search path to use.
+
+See the
+.B SEARCH PATH
+section of
+.BR manpath (5)
+for the default behaviour and details of how this environment variable is
+handled.
 .TP
 .if !'po4a'hide' .B MANWIDTH
 If
diff --git a/man/man5/manpath.man5 b/man/man5/manpath.man5
index 74f868e6..14bfa568 100644
--- a/man/man5/manpath.man5
+++ b/man/man5/manpath.man5
@@ -23,6 +23,76 @@ If the environment variable
 .RB $ MANPATH
 is already set, the information contained within %manpath_config_file% will
 not override it.
+.SH SEARCH PATH
+By default, man-db examines the user's
+.RB $ PATH .
+For each
+.I path_element
+found there,
+it adds
+.I manpath_element
+to the search path.
+
+If there is no
+.B MANPATH_MAP
+line in the configuration file for a given
+.IR path_element ,
+then it adds all of
+.IR path_element/../man ,
+.IR path_element/man ,
+.IR path_element/../share/man ,
+and
+.IR path_element/share/man
+that exist as directories to the search path.
+
+It then adds any
+.B MANDATORY_MANPATH
+entries from the configuration file to the search path.
+
+Finally, if the
+.B \-\-systems
+option is used or the
+.RB $ SYSTEM
+environment variable is set, then that should consist of a sequence of
+operating system names separated by commas or colons.
+This acts as a template, expanding the search path once more to allow access
+to other operating systems' manual pages: for each system name, man-db looks
+for that name as a subdirectory of each entry in the search path, and adds
+it to the final search path if it exists.
+A system name of
+.B man
+inserts the normal search path without subdirectories.
+For example, if the search path would otherwise have been
+.IR /usr/share/man:/usr/local/man ,
+and
+.RB $ SYSTEM
+is set to
+.IR newOS:man ,
+then the final search path will be
+.IR /usr/share/man/newOS:/usr/share/man:/usr/local/man/newOS:/usr/local/man .
+
+The
+.RB $ MANPATH
+environment variable overrides man-db's default manual page search paths.
+Most users should not need to set it.
+Its syntax is similar to the
+.RB $ PATH
+environment variable: it consists of a sequence of directory names separated
+by colons.
+It overrides the default search path described above.
+
+If the value of
+.RB $ MANPATH
+starts with a colon, then the default search path is added at its start.
+If the value of
+.RB $ MANPATH
+ends with a colon, then the default search path is added at its end.
+If the value of
+.RB $ MANPATH
+contains a double colon
+.RB ( :: ),
+then the default search path is inserted in the middle of the value, between
+the two colons.
 .SH FORMAT
 The following field types are currently recognised:
 .TP
diff --git a/man/man8/catman.man8 b/man/man8/catman.man8
index 62c886a1..4f837331 100644
--- a/man/man8/catman.man8
+++ b/man/man8/catman.man8
@@ -91,6 +91,13 @@ If
 .RB $ MANPATH
 is set, its value is interpreted as the colon-delimited manual page
 hierarchy search path to use.
+
+See the
+.B SEARCH PATH
+section of
+.BR manpath (5)
+for the default behaviour and details of how this environment variable is
+handled.
 .SH FILES
 .TP
 .if !'po4a'hide' .I %manpath_config_file%