Roland Illig wrote:
> 
> since we currently don't have a place for high-level documentation of 
> the pkgsrc infrastructure, I'd like to create it. To me it seems that 
> the best place for it would be as a third part of the current pkgsrc 
> guide. The second part could then be aimed at package developers only.
> 
> Part III would look like this:
> 
> * Intro
> * Coding style
> * Implementation of bulk builds
> * Implementation of buildlink3 and the wrappers
> * Regression tests
> * Porting pkgsrc (currently in part II)

It seems like the pkgsrc Guide should be split along the lines of 
"user", "package maintainer", and "developer".  The "user" part speaks 
to users about how to use pkgsrc, and would address issues like:

   * how to get pkgsrc
   * how to build from pkgsrc
   * how to use binary packages
   * what special shell variables can influence a binary pkg install
   * what /etc/mk.conf make variables can influence a build

The "package maintainer" part speaks to package maintainers about how to 
create and maintain packages within pkgsrc, and would address things like:

   * structure of package directory and files
   * how to create and name PLISTs
   * how to use buildlink3.mk files
   * describing the interface presented by the various frameworks
   * walk-through of a package build

The "developer" part speaks to infrastructure developers and documents 
things like:

   * the design and implementation of the various frameworks
   * coding style
   * porting pkgsrc to a new platform
   * shared library handling
   * regression tests

Does this split make more sense?  I personally find it a little hard to 
go through all of the current "developer's guide" to figure out how to 
use a framework, and when I'm documenting, I'm torn between clearly 
documenting the interface and delving into how things are done.  Having 
a split between "maintainer" and "developer" portions would make it a 
little easier to file away different blobs of information.

	Cheers,

	-- Johnny Lam <jlam@pkgsrc.org>