Improve the description of -m/-M/MANPATH/man.conf in multiple respects

after kn@ reported that the descriptions were incomplete and somewhat
inaccurate.
OK jmc@ kn@

1 files changed, 48 insertions, 35 deletions

diff --git a/usr.bin/mandoc/man.1 b/usr.bin/mandoc/man.1
index 8a7f840caf3..1c06d5ea64d 100644
--- a/usr.bin/mandoc/man.1
+++ b/usr.bin/mandoc/man.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: man.1,v 1.33 2019/03/09 15:54:46 schwarze Exp $
+.\"	$OpenBSD: man.1,v 1.34 2020/01/07 11:15:12 schwarze Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -31,7 +31,7 @@
 .\"
 .\"     @(#)man.1	8.2 (Berkeley) 1/2/94
 .\"
-.Dd $Mdocdate: March 9 2019 $
+.Dd $Mdocdate: January 7 2020 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -51,7 +51,7 @@ The
 .Nm
 utility
 displays the
-manual pages entitled
+manual page entitled
 .Ar name .
 Pages may be selected according to
 a specific category
@@ -64,7 +64,6 @@ The options are as follows:
 .Bl -tag -width Ds
 .It Fl a
 Display all matching manual pages.
-Normally, only the first page found is displayed.
 .It Fl C Ar file
 Use the specified
 .Ar file
@@ -129,31 +128,31 @@ are ignored.
 This option implies
 .Fl a .
 .It Fl M Ar path
-Override the list of standard directories which
-.Nm
-searches for manual pages.
+Override the list of directories to search for manual pages.
 The supplied
 .Ar path
 must be a colon
 .Pq Ql \&:
 separated list of directories.
-This search path may also be set using the environment variable
-.Ev MANPATH .
+This option also overrides the environment variable
+.Ev MANPATH
+and any directories specified in the
+.Xr man.conf 5
+file.
 .It Fl m Ar path
-Augment the list of standard directories which
-.Nm
-searches for manual pages.
+Augment the list of directories to search for manual pages.
 The supplied
 .Ar path
 must be a colon
 .Pq Ql \&:
 separated list of directories.
-These directories will be searched before the standard directories or
-the directories specified using the
+These directories will be searched before those specified using the
 .Fl M
-option or the
+option, the
 .Ev MANPATH
-environment variable.
+environment variable, the
+.Xr man.conf 5
+file, or the default directories.
 .It Fl S Ar subsection
 Only show pages for the specified
 .Xr machine 1
@@ -197,10 +196,6 @@ System maintenance and operation commands.
 .It 9
 Kernel internals.
 .El
-.Pp
-If not specified and a match is found in more than one section,
-the first match is selected from the following list:
-1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
 .It Fl w
 List the pathnames of all matching manual pages instead of displaying
 any of them.
@@ -214,9 +209,23 @@ The options
 .Fl fkl
 are mutually exclusive and override each other.
 .Pp
-Guidelines for writing
-man pages can be found in
-.Xr mdoc 7 .
+The search starts with the
+.Fl m
+argument if provided, then continues with the
+.Fl M
+argument, the
+.Ev MANPATH
+variable, the
+.Ic manpath
+entries in the
+.Xr man.conf 5
+file, or with
+.Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
+by default.
+Within each of these, directories are searched in the order provided.
+Within each directory, the search proceeds according to the following
+list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
+The first match found is shown.
 .Pp
 The
 .Xr mandoc.db 5
@@ -236,6 +245,10 @@ The database is kept up to date with
 which is run by the
 .Xr weekly 8
 maintenance script.
+.Pp
+Guidelines for writing
+man pages can be found in
+.Xr mdoc 7 .
 .Sh ENVIRONMENT
 .Bl -tag -width MANPATHX
 .It Ev MACHINE
@@ -286,15 +299,15 @@ manual opens a manual page at the definition of a specific
 .Ar term
 rather than at the beginning.
 .It Ev MANPATH
-The standard search path used by
-.Nm
-may be changed by specifying a path in the
+Override the standard search path which is either specified in
+.Xr man.conf 5
+or the default path.
+The format of
 .Ev MANPATH
-environment variable.
-The format of the path is a colon
+is a colon
 .Pq Ql \&:
 separated list of directories.
-Invalid paths are ignored.
+Invalid directories are ignored.
 Overridden by
 .Fl M ,
 ignored if
@@ -303,12 +316,10 @@ is specified.
 .Pp
 If
 .Ev MANPATH
-begins with a colon, it is appended to the default list;
-if it ends with a colon, it is prepended to the default list;
+begins with a colon, it is appended to the standard path;
+if it ends with a colon, it is prepended to the standard path;
 or if it contains two adjacent colons,
-the standard search path is inserted between the colons.
-If none of these conditions are met, it overrides the
-standard search path.
+the standard path is inserted between the colons.
 .It Ev PAGER
 Specifies the pagination program to use when
 .Ev MANPAGER
@@ -321,7 +332,9 @@ is used.
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact
 .It Pa /etc/man.conf
-default man configuration file
+default
+.Nm
+configuration file
 .El
 .Sh EXIT STATUS
 .Ex -std man