rework the wording in these man pages (mainly in man.conf.5) based on

some old notes I found to make it clearer and easier to understand
how the man stuff works (hopefully!).

usr.bin/man/man.1

@@ -1,4 +1,4 @@
-.\"	$NetBSD: man.1,v 1.18 2003/08/07 11:15:10 agc Exp $
+.\"	$NetBSD: man.1,v 1.19 2006/04/10 14:02:57 chuck Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -58,12 +58,8 @@
 The
 .Nm
 utility
-displays the
+displays the manual pages named on the command line.  
-.Bx
+Its options are as follows:
-man pages entitled
-.Ar name .
-.Pp
-The options are as follows:
 .Bl -tag -width indent
 .It Fl a
 Display all of the man pages for a specified
@@ -88,9 +84,10 @@ This is done by default if the standard output is not a terminal device.
 .It Fl h
 Display only the
 .Dq Tn SYNOPSIS
-lines of the requested man pages,
+lines of the requested man pages.
-in the same manner as
+For commands, this is typically the command line usage information.
-.Xr whatis 1 .
+For library functions, this is usually the required include files
+and function prototypes.
 .It Fl k
 Display the header lines for any man pages matching
 .Ar keyword Ns Pq s ,
@@ -137,7 +134,7 @@ configuration file.
 .It Fl s
 Restrict the directories that
 .Nm
-will search.
+will search to the specified section.
 The
 .Nm
 configuration file (see
@@ -146,8 +143,8 @@ specifies the possible
 .Ar section
 values that are currently available.
 .It Fl S
-Display only man pages that have the specified string in their
+Display only man pages that have the specified string in the directory
-filenames.
+part of their filenames.
 This allows the man page search process criteria to be
 narrowed without having to change the MANPATH or
 .Dq _default
@@ -168,7 +165,7 @@ option is not specified,
 there is more than one argument,
 the
 .Ql Fl k
-option is not used and the first argument is a valid section, that
+option is not used, and the first argument is a valid section, then that
 argument will be used as if specified by the
 .Ql Fl s
 option.

usr.bin/man/man.conf.5

@@ -1,4 +1,4 @@
-.\"	$NetBSD: man.conf.5,v 1.16 2003/08/07 11:15:10 agc Exp $
+.\"	$NetBSD: man.conf.5,v 1.17 2006/04/10 14:02:57 chuck Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -34,140 +34,113 @@
 .Os
 .Sh NAME
 .Nm man.conf
-.Nd configuration file for
+.Nd configuration file for manual pages
-.Xr man 1
 .Sh DESCRIPTION
 The
+.Nm
+file contains the default configuration used by 
 .Xr man 1 ,
 .Xr apropos 1 ,
-.Xr whatis 1
+.Xr whatis 1 ,
+.Xr catman 8 ,
 and
 .Xr makewhatis 8 
-commands
+to find manual pages and information about manual pages (e.g. the
-search for manual pages or their database files as specified by the
+whatis database).
-.Nm
+.Pp
-file.
+Manual pages are located by searching an ordered set of directories
-Manual pages are normally expected to be preformatted (see
+called the
-.Xr nroff 1 )
+.Dq man path
-and named with a trailing
+for a file that matches the name of the requested page.
-.Dq \.0 .
+Each directory in the search path usually has a set of subdirectories 
+in it (though this is not required).
+When subdirectories are used, there are normally two subdirectories
+for each section of the manual.
+One subdirectory contains formatted copies of that section's manual
+pages that can be directly displayed to a terminal, while the other 
+section subdirectory contains unformatted copies of the pages (see 
+.Xr nroff 1 
+and
+.Xr mandoc 7 ) .
+Formatted manual pages are normally named with a trailing
+.Dq \.0 
+suffix.
 .Pp
 The
 .Nm
-file contains two types of lines.
+file contains comment and configuration lines.  Comment lines start with
-.Pp
+the
-The first type of line is a
+.Dq #
-.Dq section
+character.   
-line, which contains a
+Blank lines are also treated as comment lines.   
-section name followed by one or more directory paths.
+Configuration lines consist of a configuration keyword followed by a 
-The directory paths may contain the normal shell globbing characters,
+configuration string.
-including curly braces
+There are two types of configuration keywords: control keywords and
-.Pq Dq {} ;
+section keywords.
-to escape a shell globbing character,
+Control keywords must start with the
-precede it with a backslash
+.Dq _
-.Pq Dq \e .
+character.
-Lines in this format specify that manual pages for the section
+The following control keywords are currently defined:
-may be found in the following directories.
-.Pp
-Section lines may contain either absolute directory paths or relative
-directory paths (but not both).
-Relative directory paths are treated
-as a list of subdirectories to append to the current directory search
-path.
-Section lines with absolute directory paths (starting with
-.Dq / )
-completely replace the current directory search path with their
-content.
-Absolute directory paths named with a trailing slash
-character are expected to contain subdirectories of manual pages, (see
-the keyword
-.Dq _subdir
-below) instead of man pages.
-These
-subdirectories are searched instead of the directory.
-.Pp
-Before searching any directory for a manual page, the
-.Xr man 1
-command always searches the subdirectory with the same name
-as the current machine type, if it exists.
-No specification of these subdirectories is necessary in the
-.Nm
-file.
-.Pp
-Section names are unrestricted except for the reserved words specified
-below; in general, you should avoid anything with a leading underscore
-.Pq Dq _
-to avoid future incompatibilities.
-.Pp
-The section named
-.Dq _default
-is the list of directories that will
-be searched if no section is specified by the user.
-.Pp
-The second type of line is preceded with a
-.Dq keyword .
-The possible keywords and their meanings are as follows:
-.Pp
 .Bl -tag -width "_version"
 .It _build
-Man file names, regardless of their format, are expected to end in
+identifies the set of suffixes used for manual pages that must be 
-a
+formatted for display and the command that should be used to format 
+them.  Manual file names, regardless of their format, are 
+expected to end in a
 .Dq \.*
 pattern, i.e. a
 .Dq \&\.
 followed by some suffix.
-The first field of a _build line lists a suffix which indicates
+The first field of a _build line contains a man page suffix specification.
-files which need to be reformatted or manipulated in some way before
+The suffix specification may contain the normal shell globbing characters 
-being displayed to the user.
+(NOT including curly braces
-The suffix may contain the normal shell globbing characters (NOT
-including curly braces
 .Pq Dq {} ) .
-The rest of the line must be a shell command line, the standard
+The rest of the _build line is a shell command line whose standard 
-output of which is the manual page in a format which may be directly
+output is a formatted manual page that can be directly displayed to 
-displayed to the user.
+the user.
 Any occurrences of the string
 .Dq %s
 in the shell command line will
-be replaced by the name of the file which is being reformatted.
+be replaced by the name of the file which is being formatted.
 .It _crunch
-The
+used by 
-.Dq _crunch
+.Xr catman 8
-section is used by catman to know how to crunch cat pages
+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.
 The rest of the line must be a shell command line, used to compress the
 formatted pages.
+.It _default
+contains the system-wide default man path used to search for man pages.
 .It _subdir
-The list (in search order) of subdirectories which will be searched in
+contains the list (in search order) of section subdirectories which will 
-any directory named with a trailing slash
+be searched in any man path directory named with a trailing slash
 .Pq Dq /
 character.
-This list is also used when a path is specified to the
+This list is also used, even if there is no trailing slash character,
+when a path is specified to the
 .Xr man 1
-utility by the user, using the
+utility by the user, by the 
 .Ev MANPATH
-environment variable or the
+environment variable, or by the
 .Fl M
 and
 .Fl m
 options.
 .It _suffix
-Man file names, regardless of their format are expected to end in
+identifies the set of suffixes used for formatted man pages
-a
+(the 
-.Dq \.*
+.Dq \.0
-pattern, i.e. a
+suffix is normally used here).
-.Dq \&\.
+Formatted man pages can be directly displayed to the user.
-followed by some suffix.
-Each field of a _suffix line is a suffix which indicates
-files which do not need to be reformatted or manipulated
-in any way, but which may be directly displayed to the user.
 Each suffix may contain the normal shell globbing characters (NOT
 including curly braces
 .Pq Dq {} ) .
 .It _version
-The version of the configuration file.
+contains the version of the configuration file.
 .It _whatdb
-The full pathname (not just a directory path) for a database to be used
+defines the full pathname (not just a directory path) for a database to 
+be used
 by the
 .Xr apropos 1
 and
@@ -181,18 +154,60 @@ precede it with a backslash
 .Pq Dq \e .
 .El
 .Pp
-Multiple specifications for all types of lines are cumulative and the
+Section configuration lines in 
-entries are used in the order listed in the file; multiple entries may
+.Nm
-be listed per line, as well.
+consist of a section keyword naming the section and a configuration
+string that defines the directory or subdirectory path that the section's
+manual pages are located in.
+The path may contain the normal shell globbing characters,
+including curly braces
+.Pq Dq {} ;
+to escape a shell globbing character,
+precede it with a backslash
+.Pq Dq \e .
+Section keywords must not start with the
+.Dq _
+character.
 .Pp
-Empty lines or lines whose first non-whitespace character is a hash
+A section path may contain either a list of absolute directories or
-mark
+a list of or relative directories (but not both).
-.Pq Dq #
+Relative directory paths are treated as a list of subdirectories that 
-are ignored.
+are appended to the current man path directory being searched.
+Section configuration lines with absolute directory paths (starting with
+.Dq / )
+completely replace the current man search path directory with their
+content.
+.Pp
+Section configuration lines with absolute directory paths ending
+with a trailing slash character are expected to contain subdirectories
+of manual pages, (see the keyword
+.Dq _subdir
+above).
+The
+.Dq _subdir
+subdirectory list is not applied to absolute section directories 
+if there is no trailing slash.
+.Pp
+In addition to the above rules, the 
+.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.
+This allows the manual to contain machine-specific man pages.   
+Note that the machine subdirectory does not need to be specified 
+in the 
+.Nm
+file.
+.Pp
+Multiple specifications for all types of 
+.Nm
+configuration lines are 
+cumulative and the entries are used in the order listed in the file; 
+multiple entries may be listed per line, as well.
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact
 .It Pa /etc/man.conf
-Standard manual directory search path.
+Standard manual configuration file.
 .El
 .Sh EXAMPLES
 Given the following