MFC r313169,r319246:

r313169 (by wblock):

Clarify some option descriptions, add a line of text to makeman to
add the slightest hint of a shade of a clue of what it does.

r319246:

Use .Xr to reference libblacklist(3), blacklistctl(8), and blacklistd(8)

16 files changed, 56 insertions, 44 deletions

diff --git a/tools/build/options/WITHOUT_BLACKLIST b/tools/build/options/WITHOUT_BLACKLIST
index 65c5097..39ccd58 100644
--- a/tools/build/options/WITHOUT_BLACKLIST
+++ b/tools/build/options/WITHOUT_BLACKLIST
@@ -1,2 +1,5 @@
 .\" $FreeBSD$
-Set this if you do not want to build blacklistd / blacklistctl.
+Set this if you do not want to build
+.Xr blacklistd 8
+and
+.Xr blacklistctl 8 .
diff --git a/tools/build/options/WITHOUT_BLACKLIST_SUPPORT b/tools/build/options/WITHOUT_BLACKLIST_SUPPORT
index 674c967..e190c53 100644
--- a/tools/build/options/WITHOUT_BLACKLIST_SUPPORT
+++ b/tools/build/options/WITHOUT_BLACKLIST_SUPPORT
@@ -1,5 +1,7 @@
 .\" $FreeBSD$
-Set to build some programs without blacklistd support, like
+Set to build some programs without
+.Xr libblacklist 3
+support, like
 .Xr fingerd 8 ,
 .Xr ftpd 8 ,
 .Xr rlogind 8 ,
diff --git a/tools/build/options/WITHOUT_CLANG_BOOTSTRAP b/tools/build/options/WITHOUT_CLANG_BOOTSTRAP
index 4a86791..e56706f 100644
--- a/tools/build/options/WITHOUT_CLANG_BOOTSTRAP
+++ b/tools/build/options/WITHOUT_CLANG_BOOTSTRAP
@@ -1,5 +1,5 @@
 .\" $FreeBSD$
-Set to not build the Clang C/C++ compiler during the bootstrap phase of the build.
-You must enable either gcc or clang bootstrap to be able to build the system,
-unless an alternative compiler is provided via
-XCC.
+Set to not build the Clang C/C++ compiler during the bootstrap phase of
+the build.
+To be able to build the system, either gcc or clang bootstrap must be
+enabled unless an alternate compiler is provided via XCC.
diff --git a/tools/build/options/WITHOUT_CROSS_COMPILER b/tools/build/options/WITHOUT_CROSS_COMPILER
index 80420c5..fc5233c 100644
--- a/tools/build/options/WITHOUT_CROSS_COMPILER
+++ b/tools/build/options/WITHOUT_CROSS_COMPILER
@@ -1,10 +1,10 @@
 .\" $FreeBSD$
 Set to not build any cross compiler in the cross-tools stage of buildworld.
-If you are compiling a different version of
+When compiling a different version of
 .Fx
-than what is installed on the system, you will need to provide an alternate
+than what is installed on the system, provide an alternate
 compiler with XCC to ensure success.
-If you are compiling with an identical version of
+When compiling with an identical version of
 .Fx
 to the host, this option may be safely used.
 This option may also be safe when the host version of
diff --git a/tools/build/options/WITHOUT_DIALOG b/tools/build/options/WITHOUT_DIALOG
index f5bc508..9a13dcf 100644
--- a/tools/build/options/WITHOUT_DIALOG
+++ b/tools/build/options/WITHOUT_DIALOG
@@ -1,2 +1,7 @@
 .\" $FreeBSD$
-Set to not build dialog(1), dialog(1,3), and dpv(1,3).
+Set to not build
+.Xr dialog 1 ,
+.Xr dialog 3 ,
+.Xr dpv 1 ,
+and
+.Xr dpv 3 .
diff --git a/tools/build/options/WITHOUT_DMAGENT b/tools/build/options/WITHOUT_DMAGENT
index 6e66bd8..d5e6209 100644
--- a/tools/build/options/WITHOUT_DMAGENT
+++ b/tools/build/options/WITHOUT_DMAGENT
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Set to not build dma Mail Transport Agent
+Set to not build dma Mail Transport Agent.
diff --git a/tools/build/options/WITHOUT_DOCCOMPRESS b/tools/build/options/WITHOUT_DOCCOMPRESS
index ba08df7..ec4de74 100644
--- a/tools/build/options/WITHOUT_DOCCOMPRESS
+++ b/tools/build/options/WITHOUT_DOCCOMPRESS
@@ -1,3 +1,3 @@
 .\" $FreeBSD$
-Set to not to install compressed system documentation.
+Set to not install compressed system documentation.
 Only the uncompressed version will be installed.
diff --git a/tools/build/options/WITHOUT_GPL_DTC b/tools/build/options/WITHOUT_GPL_DTC
index 5dc42ce..3d91696 100644
--- a/tools/build/options/WITHOUT_GPL_DTC
+++ b/tools/build/options/WITHOUT_GPL_DTC
@@ -1,3 +1,3 @@
 .\" $FreeBSD$
-Set to build the BSD licensed version of the device tree compiler, instead of the
-GPL'd one from elinux.org.
+Set to build the BSD licensed version of the device tree compiler rather
+than the GPLed one from elinux.org.
diff --git a/tools/build/options/WITHOUT_INSTALLLIB b/tools/build/options/WITHOUT_INSTALLLIB
index e2aba136..bb8f501 100644
--- a/tools/build/options/WITHOUT_INSTALLLIB
+++ b/tools/build/options/WITHOUT_INSTALLLIB
@@ -1,6 +1,6 @@
 .\" $FreeBSD$
-Set this if you do not want to install optional libraries.
-For example when creating a
+Set this if to not install optional libraries.
+For example, when creating a
 .Xr nanobsd 8
 image.
 .Bf -symbolic
diff --git a/tools/build/options/WITHOUT_KERBEROS b/tools/build/options/WITHOUT_KERBEROS
index 8f562ec..fab303b 100644
--- a/tools/build/options/WITHOUT_KERBEROS
+++ b/tools/build/options/WITHOUT_KERBEROS
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Set this if you do not want to build Kerberos 5 (KTH Heimdal).
+Set this to not build Kerberos 5 (KTH Heimdal).
diff --git a/tools/build/options/WITH_CCACHE_BUILD b/tools/build/options/WITH_CCACHE_BUILD
index 86b7f1a..97a45ea 100644
--- a/tools/build/options/WITH_CCACHE_BUILD
+++ b/tools/build/options/WITH_CCACHE_BUILD
@@ -5,9 +5,9 @@ for the build.
 No configuration is required except to install the
 .Sy devel/ccache
 package.
-Using with
-.Xr distcc 1
-should set
+When using with
+.Xr distcc 1 ,
+set
 .Sy CCACHE_PREFIX=/usr/local/bin/distcc .
 The default cache directory of
 .Pa $HOME/.ccache
diff --git a/tools/build/options/WITH_DIRDEPS_BUILD b/tools/build/options/WITH_DIRDEPS_BUILD
index 334c483..38599cb 100644
--- a/tools/build/options/WITH_DIRDEPS_BUILD
+++ b/tools/build/options/WITH_DIRDEPS_BUILD
@@ -11,23 +11,24 @@ Makefile.depend files found in each directory.
 .Pp
 The build can be started from anywhere, and behaves the same.
 The initial instance of
-.Xr make 1 
+.Xr make 1
 recursively reads
 .Va DIRDEPS
-from Makefile.depend
+from
+.Pa Makefile.depend ,
 computing a graph of tree dependencies from the current origin.
 Setting
 .Va NO_DIRDEPS
-will skip checking dirdep dependencies and will only build in the current
+skips checking dirdep dependencies and will only build in the current
 and child directories.
 .Va NO_DIRDEPS_BELOW
-will skip building any dirdeps and only build the current directory.
+skips building any dirdeps and only build the current directory.
 .Pp
 This also utilizes the
 .Va WITH_META_MODE
 logic for incremental builds.
 .Pp
-The build will hide commands ran unless
+The build hides commands executed unless
 .Va NO_SILENT
 is defined.
 .Pp
diff --git a/tools/build/options/WITH_INSTALL_AS_USER b/tools/build/options/WITH_INSTALL_AS_USER
index da49014..6d130e1 100644
--- a/tools/build/options/WITH_INSTALL_AS_USER
+++ b/tools/build/options/WITH_INSTALL_AS_USER
@@ -4,6 +4,6 @@ files with owner and group attributes set to that of the user running
 the
 .Xr make 1
 command.
-The user still has to set the
+The user still must set the
 .Va DESTDIR
 variable to point to a directory where the user has write permissions.
diff --git a/tools/build/options/WITH_META_MODE b/tools/build/options/WITH_META_MODE
index 9f7bade..143a793 100644
--- a/tools/build/options/WITH_META_MODE
+++ b/tools/build/options/WITH_META_MODE
@@ -1,22 +1,22 @@
 .\" $FreeBSD$
-Creates
+Create
 .Xr make 1
 meta files when building, which can provide a reliable incremental build when
 using
 .Xr filemon 4 .
-The meta file is created in the OBJDIR as
+The meta file is created in OBJDIR as
 .Pa target.meta .
-These meta files track the command ran, its output, and the current directory.
+These meta files track the command that was executed, its output, and the
+current directory.
 The
 .Xr filemon 4
 module is required unless
 .Va NO_FILEMON
 is defined.
-When the module is loaded, any files used by the commands executed will be
-tracked as
-dependencies for the target in its meta file.
-The target will be considered out-of-date and rebuilt if any of the following
-are true compared to the last build:
+When the module is loaded, any files used by the commands executed are
+tracked as dependencies for the target in its meta file.
+The target is considered out-of-date and rebuilt if any of these
+conditions are true compared to the last build:
 .Bl -bullet -compact
 .It
 The command to execute changes.
@@ -38,10 +38,10 @@ Files read, written, executed or linked are missing.
 .El
 The meta files can also be useful for debugging.
 .Pp
-The build will hide commands ran unless
+The build hides commands that are executed unless
 .Va NO_SILENT
 is defined.
-Errors will cause
+Errors cause
 .Xr make 1
 to show some of its environment for further debugging.
 .Pp
diff --git a/tools/build/options/WITH_STAGING_MAN b/tools/build/options/WITH_STAGING_MAN
index 474b45d..5cd75ab 100644
--- a/tools/build/options/WITH_STAGING_MAN
+++ b/tools/build/options/WITH_STAGING_MAN
@@ -1,2 +1,2 @@
 .\" $FreeBSD$
-Enable staging of MAN pages to stage tree.
+Enable staging of man pages to stage tree.
diff --git a/tools/build/options/makeman b/tools/build/options/makeman
index 60dc3b6..ad23785 100755
--- a/tools/build/options/makeman
+++ b/tools/build/options/makeman
@@ -22,7 +22,7 @@ set -o errexit
 export LC_ALL=C
 
 t=$(mktemp -d -t makeman)
-trap 'test -d $t && rm -rf $t' exit
+# trap 'test -d $t && rm -rf $t' exit
 
 srcdir=$(realpath ../../..)
 make="make -C $srcdir -m $srcdir/share/mk"
@@ -132,6 +132,7 @@ show()
 
 main()
 {
+	echo "building src.conf.5 man page from files in ${PWD}" >&2
 
 	fbsdid='$'FreeBSD'$'
 	cat <<EOF
@@ -222,11 +223,11 @@ even if they would be set to
 .Dq Li FALSE
 or
 .Dq Li NO .
-Just the existence of an option will cause
-it to be honoured by
+The presence of an option causes
+it to be honored by
 .Xr make 1 .
 .Pp
-The following list provides a name and short description for variables
+This list provides a name and short description for variables
 that can be used for source builds.
 .Bl -tag -width indent
 EOF
@@ -251,7 +252,7 @@ EOF
 		sed -e'/\$FreeBSD.*\$/d' ${opt}
 		if [ -n "${targets}" ] ; then
 			echo '.Pp'
-			echo 'It is a default setting on'
+			echo 'This is a default setting on'
 			echo $(echo ${targets} | sed -e's/ /, /g' -e's/\(.*\), /\1 and /').
 		fi
 
@@ -283,7 +284,7 @@ EOF
 		havedeps=0
 		if [ -s $t/deps ] ; then
 			havedeps=1
-			echo 'When set, it also enforces the following options:'
+			echo 'When set, it enforces these options:'
 			echo '.Pp'
 			echo '.Bl -item -compact'
 			while read opt2 ; do
@@ -297,7 +298,7 @@ EOF
 			if [ ${havedeps} -eq 1 ] ; then
 				echo '.Pp'
 			fi
-			echo 'When set, the following options are also in effect:'
+			echo 'When set, these options are also in effect:'
 			echo '.Pp'
 			echo '.Bl -inset -compact'
 			while read opt2 ; do