Improved the documentation a bit.

1 files changed, 57 insertions, 36 deletions

diff --git a/mk/defaults/mk.conf b/mk/defaults/mk.conf
index a6e3149d39d..a1e8ac3182b 100644
--- a/mk/defaults/mk.conf
+++ b/mk/defaults/mk.conf
@@ -1,4 +1,4 @@
-# $NetBSD: mk.conf,v 1.143 2006/12/28 16:09:33 obache Exp $
+# $NetBSD: mk.conf,v 1.144 2007/01/02 17:56:52 rillig Exp $
 #
 
 # This file provides default values for variables that may be overridden
@@ -37,12 +37,18 @@ GZIP?=	-9
 # Default: -9
 
 #MAKE_JOBS=	3
-# Set to maximum number of jobs ("make -j") for make to run at one time.
-# Possible: a positive integer (e.g. 17)
-# Default: not defined
-# Note that this is in testing. Some packages will not build with this.
-# Disabling this for an individual package can be done by setting
-# MAKE_JOBS_SAFE=NO within the per package Makefile.
+#	When defined, specifies the maximum number of jobs ("make -j")
+#	that are run in parallel when building packages. By default, no
+#	parallelization takes place.
+#
+#	Possible values: any positive integer. Useful values are around
+#	the number of processors on the machine.
+#
+#	Default value: (undefined)
+#
+#	Warning: This is experimental. Some packages will not build with
+#	this. Disabling this for an individual package can be done by
+#	setting MAKE_JOBS_SAFE=NO within the per package Makefile.
 
 #MKCRYPTO= no
 # If not YES or yes, don't fetch, build or install crypto packages.
@@ -66,23 +72,25 @@ GZIP?=	-9
 # Default: .tgz
 
 PKGSRC_LOCKTYPE?= none
-# The type of locking which will be done if competing processes attempt to
-# do work on one package directory simultaneously.
-# + Locking requires that OBJHOSTNAME is set.
-# + Locking may require the pkgsrc/pkgtools/shlock package to be installed
-#   on certain OS types.
-# + Sleep locking means that the process will sleep for ${PKGSRC_SLEEPSECS}
-#   seconds, then try to acquire the lock, and sleeping again if it's not
-#   available.
-# + Once locking will try once to acquire the lock, and then fail.
-# Possible: none, sleep, once
-# Default: none
+#	The type of locking that will be done if competing processes
+#	attempt to do work on one package directory simultaneously.
+#
+#	Possible values:
+#	* none: No locking takes place at all.
+#	* once: When the lock has already been aquired by another
+#	  process, the current process is terminated.
+#	* sleep: When the lock has already been acquired by another
+#	  process, the current process will sleep for PKGSRC_SLEEPSECS
+#	  seconds and then try again.
+#
+#	Note: Locking requires that OBJHOSTNAME is set.
+#
 
 PKGSRC_SLEEPSECS?= 5
-# The number of seconds to wait when PKGSRC_LOCKTYPE is sleep
-# Possible: a positive integer
-# Default: 5
-
+#	The number of seconds to wait when PKGSRC_LOCKTYPE is sleep.
+#
+#	Possible values: any positive integer
+#
 
 #
 # The following values are used to manage the packages collection as a whole.
@@ -187,9 +195,13 @@ PREFER_NATIVE_PTHREADS?=	yes
 # Default: not defined
 
 LOCALBASE?=	/usr/pkg
-# Where non-X-based packages will be installed
-# Possible: any path
-# Default: /usr/pkg
+#	This is the base directory where all packages will be installed.
+#
+#	Possible values: Any absolute path that does not contain special
+#	characters.
+#
+#	See also: PREFIX, VARBASE
+#
 
 CROSSBASE?=	${LOCALBASE}/cross
 # Where "cross" category packages install
@@ -221,18 +233,27 @@ VARBASE?=	/var
 # Default: ${X11PREFIX} or where openmotif or lesstif is installed
 
 PKGINFODIR?=	info
-# Pathname relative to ${PREFIX} of directory holding the
-# info files and the info "dir" (index) file.
-# Possible: any path you like, e.g. share/info.
-# Default: info (i.e. /usr/pkg/info)
-# NOTE: the support for custom setting (not "info") is not complete.
+#	The subdirectory of PREFIX that holds the GNU info files and the
+#	directory index file ("dir").
+#
+#	Possible: A sane pathname.
+#
+#	Examples:
+#	* share/info
+#
+#	Note: the support for custom setting (not "info") is not complete.
+#
 
 PKGMANDIR?=	man
-# Pathname relative to ${PREFIX} of directory holding the
-# manual pages and man directories.
-# Possible: any path you like, e.g. share/man.
-# Default: man (i.e. /usr/pkg/man)
-# NOTE: the support for custom setting (not "man") is not complete.
+#	The subdirectory of PREFIX that holds the manual pages and their
+#	subdirectories (e.g. man1, man7).
+#
+#	Possible: Any sane pathname.
+#
+#	Examples:
+#	* share/man
+#
+#	Note: the support for custom setting (not "man") is not complete.
 
 # USE_XPKGWEDGE?=	yes
 # Whether we should use xpkgwedge or not to install all packages into
@@ -262,7 +283,7 @@ DISTDIR?=	${PKGSRCDIR}/distfiles
 # Default: /usr/pkgsrc/distfiles
 
 #DIST_PATH=	/cdrom/0/distfiles:${HOME}/distfiles
-# colon-delimited list of directories in which to search for
+# Colon-delimited list of directories in which to search for
 # ${DISTFILES} and ${PATCHFILES}.  If the requested file is not in any
 # of the directories in ${DIST_PATH}, it will be downloaded into
 # ${DISTDIR}.  If the requested file is in one of the directories in