[src/trunk]: src/usr.bin/man man.conf.5: add details about the machine line a...

[gutteridge <gutteridge%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/bf8f2687b9e8
branches:  trunk
changeset: 366836:bf8f2687b9e8
user:      gutteridge <gutteridge%NetBSD.org@localhost>
date:      Sat Jun 18 02:19:07 2022 +0000

description:
man.conf.5: add details about the machine line and search order

Also, tweak some grammar, style, and markup while here.

diffstat:

 usr.bin/man/man.conf.5 |  25 +++++++++++++++----------
 1 files changed, 15 insertions(+), 10 deletions(-)

diffs (79 lines):

diff -r 2eedb70581a0 -r bf8f2687b9e8 usr.bin/man/man.conf.5
--- a/usr.bin/man/man.conf.5    Sat Jun 18 02:14:39 2022 +0000
+++ b/usr.bin/man/man.conf.5    Sat Jun 18 02:19:07 2022 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: man.conf.5,v 1.27 2016/06/16 15:11:43 abhinav Exp $
+.\"    $NetBSD: man.conf.5,v 1.28 2022/06/18 02:19:07 gutteridge Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"    @(#)man.conf.5  8.5 (Berkeley) 1/2/94
 .\"
-.Dd June 16, 2016
+.Dd June 18, 2022
 .Dt MAN.CONF 5
 .Os
 .Sh NAME
@@ -45,8 +45,9 @@
 .Xr catman 8 ,
 and
 .Xr makemandb 8
-to find manual pages and information about manual pages (e.g. the
-whatis database).
+to find manual pages and information about manual pages (e.g., the
+.Xr whatis 1
+database).
 .Pp
 Manual pages are located by searching an ordered set of directories
 called the
@@ -106,8 +107,9 @@
 Used by
 .Xr catman 8
 to determine how to crunch formatted pages
-which originally were compressed man pages: The first field lists a suffix
-which indicates what kind of compression were used to compress the man page.
+which originally were compressed man pages.
+The first field lists a suffix which indicates what kind of compression was
+used to compress the man page.
 The rest of the line must be a shell command line, used to compress the
 formatted pages.
 There should be exactly one occurrence of the string
@@ -159,13 +161,15 @@
 .It _ Ns Aq machine
 Defines additional paths to be searched for the particular
 .Dv machine
-whose literal value is taken from
+hardware name whose literal value is taken from
 .Xr uname 1
 .Fl m .
 For example on an
 .Dv amd64 ,
 .Dv _amd64
-is used.
+is used, where
+.Dq x86
+is commonly supplied as an alternate machine path to also search.
 .El
 .Pp
 Section configuration lines in
@@ -184,7 +188,7 @@
 character.
 .Pp
 A section path may contain either a list of absolute directories or
-a list of or relative directories (but not both).
+a list of relative directories (but not both).
 Relative directory paths are treated as a list of subdirectories that
 are appended to the current man path directory being searched.
 Section configuration lines with absolute directory paths (starting with
@@ -206,7 +210,8 @@
 .Xr man 1
 command also always checks in each directory that it searches for
 a subdirectory with the same name as the current machine type.
-If the machine-specific directory is found, it is also searched.
+If a machine-specific subdirectory is found, it is also searched
+before the parent directory is.
 This allows the manual to contain machine-specific man pages.
 Note that the machine subdirectory does not need to be specified
 in the