This is a multi-part message in MIME format.
--------------050005060304030601000300
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Hubert Feyrer wrote:
> On Sat, 8 Oct 2005, Roland Illig wrote:
> 
>> I'd like to add a chapter called "Variable reference" to the pkgsrc 
>> guide to have a place where all public variables are explained and 
>> listed (alphabetically and categorized).
>>
>> Any objections? suggestions? ideas?
> 
> 
> When we started pkgsrc, we kept the list at the top of what's bsd.pk.mk 
> today. Then for some reason it was split out into the base system's 
> packages.7 where it's rotting right now. In addition, a number of other 
> files have popped up in pkgsrc/mk, which seem to be back at documenting 
> their variables at the top of the files.
> 
> While I think having some varible index is nice, I also think that the 
> actual documentation should be kept near the code, and maybe extracted 
> from there into the pkgsrc guide then.

Then maybe this file is something for you. Just install the appended 
file into pkgsrc/mk/ and add the following line to your mk.conf file:

.sinclude "../../mk/pkgsrc.help.mk"

This makes the following possible:

$ make help
usage: /usr/bin/make help TOPIC=<VARNAME>

$ make help TOPIC=BUILD_DIRS
No help found for BUILD_DIRS.

$ make help TOPIC=APACHE_USER
===========================================================================
APACHE_USER?=   www
# Used in apache, apache2, isap, and smb2www to specify the user
# allowed to execute the `suexec' wrapper.  Expected to be the user the
# httpd server normally runs as.
# Possible: any user name
# Default: www
===========================================================================

Roland

--------------050005060304030601000300
Content-Type: text/plain;
 name="pkgsrc.help.mk"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="pkgsrc.help.mk"

# $NetBSD$
#

# This is the integrated pkgsrc online help system. To query for the
# meaning of a variable, run "make help TOPIC=VARNAME". All variables from
# certain pkgsrc Makefile fragments that have inline comments are eligible
# for querying.

.if !defined(_PKGSRC_HELP_MK)
_PKGSRC_HELP_MK=	# defined

_HELP_FILES=		# empty
_HELP_FILES+=		mk/defaults/mk.conf
_HELP_FILES+=		mk/bsd.prefs.mk
_HELP_FILES+=		mk/bsd.pkg.mk

_HELP_AWK= \
	BEGIN {								\
		hline = "===============";				\
		hline = hline hline hline hline hline;			\
		found = 0;						\
		var = 0; comment = 0; n = 0; lines[n++] = hline;	\
	}								\
	/./ {								\
		lines[n++] = $$0;					\
	}								\
	($$1 == VARNAME"?=") || ($$1 == "\#"VARNAME"=") {		\
		var = 1;						\
	}								\
	/^\#/ {								\
		comment = 1;						\
	}								\
	/^$$/ {								\
		if (var == 1 && comment == 1) {				\
			found = 1;					\
			for (i = 0; i < n; i++) { print lines[i]; }	\
		}							\
		var = 0; comment = 0; n = 0; lines[n++] = hline;	\
	}								\
	END {								\
		if (found) {						\
			print hline;					\
		} else {						\
			print "No help found for " VARNAME ".";		\
		}							\
	}

.if !defined(TOPIC) && defined(VARNAME)
TOPIC=		${VARNAME}
.endif

help:
.if !defined(TOPIC)
	@${ECHO} "usage: "${MAKE:Q}" help TOPIC=<VARNAME>" 1>&2
.else
	@cd ${PKGSRCDIR};						\
	{ for i in ${_HELP_FILES}; do ${CAT} "$$i"; ${ECHO} ""; done; }	\
	| ${AWK} -v VARNAME=${TOPIC} '${_HELP_AWK:M*}'
.endif

.endif

--------------050005060304030601000300--