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 <tv@duh.org> <tv@pobox.com> <todd@vierling.name>