Subject: Re: Documenting user-variables
To: Hubert Feyrer <firstname.lastname@example.org>
From: Todd Vierling <email@example.com>
Date: 06/04/2005 12:47:16
On Sat, 4 Jun 2005, Hubert Feyrer wrote:
> > It was designed to document the *user-visible* parts of pkgsrc, which most
> > definitely includes everything a user can set in mk.conf (which includes,
> > AFAICT, almost all of what's in packages.7).
> Seems you know more than who did (part of) that "design" then. :)
Then the Guide is not designed to contain *user documentation*? That's what
nearly every doc item in packages.7 is.
Documentation about mk.conf variables is not internal pkgsrc-maintainer
information. Users of pkgsrc need to see that information in a more visible
location than just the top of bsd.pkg.mk.
> > Documenting internal variables used for .mk processing purposes in
> > bsd.pkg.mk would be OK, but the user-visible ones should be in real
> > documentation, not hidden in a .mk file.
> I think the moving to src/.../packages.7 has shown how well it's maintained
> when it's away from the code, and I'm afraid this will happen in the pkgsrc
> guide as well.
Many pkgsrc folk don't even have src/ checked out (save perhaps for
src/sys/). Hell, I don't anymore. But I certainly have a full pkgsrc tree
checked out, including pkgsrc/doc/guide.
Maintaining the Guide is supposed to be a first-order responsibility of
people who modify pkgsrc infrastructure; I see user variable docs as a
natural part of that same responsibility.
> But either way, would you be interested in moving packages.7 back into pkgsrc,
> into bsd.pkg.mk and (if you insist) the pkgsrc guide?
I didn't start this thread. However, if I can block out the time this
weekend to do so, I'll let you know.
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.
-- Todd Vierling <firstname.lastname@example.org> <email@example.com> <firstname.lastname@example.org>