The ports(7) man page reads:
-----------------------------------------------------------------------
and use the update target with FORCE_UPDATE set to `Yes' for the
build.
...
PORT VARIABLES
These can be changed in the environment, or in /etc/mk.conf for
persistence. They can also be set on make's command line,
e.g., make VAR_FOO=foo
Boolean variables should be set to Yes instead of simply being
defined, for uniformity and future compatibility.
Variable names starting with _ are private to the ports
infrastructure, should not be changed by the user, and are
liable to change without notice.
...
CLEANDEPENDS
If set to Yes, let `clean' recurse to dependencies.
FETCH_PACKAGES
If set to ``Yes'', try to use pkg_add(1) to install the missing
packages from PKG_PATH.
-----------------------------------------------------------------------
1.) The majority of the scripts in ports/infrastructure do not
bother to check /etc/mk.conf at all, so saying "or" and "also" seems
unwise without context. The best answer seems to be to preface the
statement with, "When running make ..."
2.) There are places where even the environment is not checked for these
variables by the infrastructure scripts (as an example, see
infrastructure/fetch/check-distfiles). First, I'll fix all the scripts so
use the environment. Once those diffs are in, and if wanted, I'll work
on making them parse the /etc/mk.conf somehow.
3.) The convention of using `Yes' is not quoted consistently, or quoted
at all in various places.
4.) There's no mention of how to set a boolean variable to false if the
default is true.
5.) Considering the precedence set by other /etc/*.conf files like
rc.conf, using all caps of "YES" or "NO" for true/false would be more
consistent. --Since Marc is the main chef of the ports system, this
should probably be his call. Chefs' choice and all that.
6.) Though it mentions the private "_*" variables, it does not list
them, so this results in basically outlawing all variables which start
with and underscore. --thoughts?
NOTE: Since single quote mdoc (.Sq) results in back-tick and apostrophe,
it seems better to use straight double quotes (.Qq) since you would
typically write something like:
VARIABLE_NAME="YES"
or
PATH="${PATH}:/mycrud/bin"
Suggested diff as follows. Will recook without capitalization if desired.
jcr
-----------------------------------------------------------------------
Index: ports.7
===================================================================
RCS file: /cvs/src/share/man/man7/ports.7,v
retrieving revision 1.79
diff -u ports.7
--- ports.7 11 Oct 2009 21:07:06 -0000 1.79
+++ ports.7 4 Mar 2010 00:27:56 -0000
@@ -242,7 +242,7 @@
Defining
.Ev NO_CHECKSUM
to
-.Dv Yes
+.Qq YES
will skip this step.
Sometimes, distfiles change without warning.
The main
@@ -269,7 +269,7 @@
Defining
.Ev NO_DEPENDS
to
-.Dv Yes
+.Qq YES
will skip this step.
.It Ar extract
Expand the distfile into a work directory.
@@ -307,7 +307,7 @@
This does not recurse to dependencies unless
.Ev CLEANDEPENDS
is defined to
-.Dv Yes .
+.Qq YES .
.It Ar distclean
Remove the port's distfile(s).
This does not recurse to dependencies.
@@ -398,7 +398,7 @@
If
.Ev FORCE_UPDATE
is set to
-.Sq Yes ,
+.Qq YES ,
dependencies will also be updated first, and packages will always be updated,
even if there is no difference between the old and the new packages.
.Pp
@@ -422,7 +422,7 @@
and
.Ev BULK
are set to
-.Sq Yes
+.Qq YES
for a package build, some shortcuts are taken to allow cleaning up working
directories on the fly.
.Pp
@@ -447,7 +447,7 @@
target with
.Ev FORCE_UPDATE
set to
-.Sq Yes
+.Qq YES
for the build.
.Sh NETWORK CONFIGURATION
The variables pertaining to network access have been marshalled into
@@ -459,13 +459,13 @@
.Bl -tag -width MASTER_SITES
.It Ev MASTER_SITE_OPENBSD
If set to
-.Dv Yes ,
+.Qq YES ,
include the master
.Ox
site when fetching files.
.It Ev MASTER_SITE_FREEBSD
If set to
-.Dv Yes ,
+.Qq YES ,
include the master
.Fx
site when fetching files.
@@ -569,16 +569,23 @@
$ env SUBPACKAGE="-server" make deinstall
.Ed
.Sh PORT VARIABLES
-These can be changed in the environment, or in
+When running make, these variables can be set in the environment, or set in
.Pa /etc/mk.conf
-for persistence.
-They can also be set on make's command line, e.g.,
+for persistence, or set on make's command line, e.g.,
.Ic make VAR_FOO=foo
.Pp
-Boolean variables should be set to
-.Dv Yes
-instead of simply being defined, for uniformity and future compatibility.
+The
+.Ic ${PORTSDIR}/infrastructure/
+scripts will only acknowledge these variables when set in the environment.
.Pp
+Boolean variables which are flase by default should be set to
+.Qq YES
+instead of simply being defined. Boolean variables which are true by defaut
+should be set to
+.Qq NO
+instead of simply being undefined.
+This is for uniformity and future compatibility.
+.Pp
Variable names starting with _ are private to the ports infrastructure,
should not be changed by the user, and are liable to change without notice.
.Bl -tag -width MASTER_SITES
@@ -618,9 +625,9 @@
Primary sites for distribution files if not found locally.
.It Ev CLEANDEPENDS
If set to
-.Dv Yes ,
+.Qq YES ,
let
-.Sq clean
+.Ar clean
recurse to dependencies.
.It Ev FETCH_CMD
Command to use to fetch files.
@@ -628,7 +635,7 @@
.Xr ftp 1 .
.It Ev FETCH_PACKAGES
If set to
-.Dq Yes ,
+.Qq YES ,
try to use
.Xr pkg_add 1
to install the missing packages from
@@ -641,7 +648,7 @@
If defined, only operate on a port if it can be installed 100% automatically.
.It Ev USE_SYSTRACE
Set to
-.Sq Yes
+.Qq YES
to protect the
.Ar configure , build ,
and
--
