ports/63335: [patch] try to clarify uses of port metavariables in bsd.port.mk

[Mark Linimon]

>Number:         63335
>Category:       ports
>Synopsis:       [patch] try to clarify uses of port metavariables in bsd.port.mk
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-ports-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Tue Feb 24 23:20:10 PST 2004
>Closed-Date:
>Last-Modified:
>Originator:     Mark Linimon
>Release:        FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #3: Thu Jan 22 20:41:05 CST 2004 root at lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
	Every time I want, or need, to use a new or existing port configuration
	knob, I have to go look up what the naming conventions are.  The
	following patch adds a few lines to bsd.port.mk right at the point
	where the first uses are introduced.  Perhaps adding this will help
	somebody else keep from going cross-eyed, as well.

	Note: from the email I've read, I *think* this is the right
	summary.  Someone please correct me if I'm wrong ...
>How-To-Repeat:
	(n/a)
>Fix:

Index: bsd.port.mk
===================================================================
RCS file: /mnt/FreeBSD/ncvs/ports/Mk/bsd.port.mk,v
retrieving revision 1.484
diff -u -r1.484 bsd.port.mk
--- bsd.port.mk	4 Feb 2004 04:27:04 -0000	1.484
+++ bsd.port.mk	25 Feb 2004 07:04:24 -0000
@@ -179,10 +179,17 @@
 # ONLY_FOR_ARCHS - Only build ports if ${ARCH} matches one of these.
 # NOT_FOR_ARCHS  - Only build ports if ${ARCH} doesn't match one of these.
 #
+# These variables control options about how a port gets built and/or
+# are shorthand notations for common sets of dependencies.
 # Use these if your port uses some of the common software packages. By
 # convention these should be set to 'yes', although they only need to be
 # defined.  (Defaults: not set, unless explicitly indicated below.)
 #
+# Note: the distinction between the USE_* and WANT_* variables, and the
+# WITH_* and WITHOUT_* variables, are that the former are restricted to
+# usage inside the ports framework, and the latter are reserved for user-
+# settable options.  (Setting USE_* in /etc/make.conf is always wrong).
+#
 # USE_BZIP2		- Says that the port tarballs use bzip2, not gzip, for
 #				  compression.
 # USE_ZIP		- Says that the port distfile uses zip, not tar w/[bg]zip
>Release-Note:
>Audit-Trail:
>Unformatted: