Todd Vierling wrote:
> Regardless, the doc for any given datum should be in exactly one place --
> IMNSHO, the Guide for user-settings docs, and possibly some other place
> (such as the header for bsd.pkg.mk) for internal variables.

Current practice for some of the newer files is to document the 
_interface_ to each file in the header comment. Nice examples are 
bsd.pkg.extract.mk and bsd.options.mk. The underlying structure is to list:

- the variables that can be set in the package Makefile
- the variables that can be set in mk.conf
- the variables that can be used after inclusion of the file

Of course this scheme is not applicable to bsd.pkg.mk, as the file is 
much too big for documenting it in the header. That's why some parts of 
it got their own files (e.g. bsd.pkg.extract.mk). In these cases the 
interface to the file becomes short enough to be documented within an 
hour, which is not much work.

So the headers are not used for documenting _internal_ variables but for 
documenting the interface. I would like to have the documentation in 
these files and maybe just have an example usage and some pointers to 
the relevant files in the pkgsrc guide. Example:

<example>

13.3.1   Patching multiple files in a uniform way (SUBST_*)

When you need to patch numerous files in a trivial way, like changing 
"extern int errno;" to "#include <errno.h>", you can use the following 
code in your package Makefile.

SUBST_CLASSES+=		errno
SUBST_STAGE.errno=	pre-configure
SUBST_FILES.errno=	*.c */*.c */*/*.c
SUBST_SED.errno=	-e 's/^extern int errno;/\#include <errno.h>/'

For more details, see the comment at the beginning of the mk/subst.mk file.

</example>

Roland