* mandoc: Improve the description of -m/-M/MANPATH/man.conf in multiple
@ 2020-01-07 11:17 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2020-01-07 11:17 UTC (permalink / raw)
To: source
Log Message:
-----------
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@
Modified Files:
--------------
mandoc:
man.1
Revision Data
-------------
Index: man.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man.1,v
retrieving revision 1.35
retrieving revision 1.36
diff -Lman.1 -Lman.1 -u -p -r1.35 -r1.36
--- man.1
+++ man.1
@@ -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 command
.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 defini
.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
--
To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2020-01-07 11:17 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-07 11:17 mandoc: Improve the description of -m/-M/MANPATH/man.conf in multiple schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).