[pkgsrc/trunk]: pkgsrc/mk/defaults Improved the documentation a bit.

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/5112cb66c1ba
branches:  trunk
changeset: 523143:5112cb66c1ba
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Tue Jan 02 17:56:52 2007 +0000

description:
Improved the documentation a bit.

diffstat:

 mk/defaults/mk.conf |  93 ++++++++++++++++++++++++++++++++--------------------
 1 files changed, 57 insertions(+), 36 deletions(-)

diffs (139 lines):

diff -r 2d02314efb27 -r 5112cb66c1ba mk/defaults/mk.conf
--- a/mk/defaults/mk.conf       Tue Jan 02 17:54:32 2007 +0000
+++ b/mk/defaults/mk.conf       Tue Jan 02 17:56:52 2007 +0000
@@ -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 @@
 # 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 @@
 # 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 @@
 # 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 @@
 # 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 @@
 # 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