On 10/8/05, Berndt Josef Wulf <wulf@ping.net.au> wrote:
> On Sat, 8 Oct 2005 23:06, Julio M. Merino Vidal wrote:
> > On 10/8/05, Roland Illig <rillig@netbsd.org> wrote:
> > > Hi,
> > >
> > > 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?
> >
> > There are multiple sections in the guide that list and give detailed
> > explanations
> > of some variables, with the appropriate context.  Repeating that in a
> > variable reference chapter could be redundant, I think.
> >
> > What about having an automatically generated variable index that links =
to
> > the appropriate chapters or sections?
>
> That's the problem, it gives explanations of some variables but not all.

Then an appropriate chapter/section ought to be written for the guide that
describes the missing variable in an appropriate context.  Related informat=
ion
is very valuable, specially when you have to document similar variables.
For example, see the pkginstall chapter to see what I mean:
http://www.netbsd.org/Documentation/pkgsrc/pkginstall.html

This is why I'm not fond on the idea of having a mere list of variables wit=
h
their descriptions, be it in a manual page, at the top of .mk files,
or wherever.

--
Julio M. Merino Vidal <jmmv84@gmail.com>
http://www.livejournal.com/users/jmmv/
The NetBSD Project - http://www.NetBSD.org/