aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/man.1
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2020-01-07 11:16:33 +0000
committerIngo Schwarze <schwarze@openbsd.org>2020-01-07 11:16:33 +0000
commitdd7adfb35f46c08e5910f4aa1cbdcef986e49eb5 (patch)
tree95eff570269b1b2288aa1f1b175507d3a1d276da /man.1
parent5a317ea1cdb4526d1f081d9c2176e90001bdc79c (diff)
downloadmandoc-dd7adfb35f46c08e5910f4aa1cbdcef986e49eb5.tar.gz
mandoc-dd7adfb35f46c08e5910f4aa1cbdcef986e49eb5.tar.zst
mandoc-dd7adfb35f46c08e5910f4aa1cbdcef986e49eb5.zip
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@
Diffstat (limited to 'man.1')
-rw-r--r--man.183
1 files changed, 48 insertions, 35 deletions
diff --git a/man.1 b/man.1
index 0d2976ba..b72d2433 100644
--- a/man.1
+++ b/man.1
@@ -1,4 +1,4 @@
-.\" $Id: man.1,v 1.35 2019/03/09 15:55:01 schwarze Exp $
+.\" $Id: man.1,v 1.36 2020/01/07 11:16:33 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