>Number:         5356
>Category:       pkg
>Synopsis:       package system documentation is not simple or thorough enough
>Confidential:   no
>Severity:       critical
>Priority:       high
>Responsible:    gnats-admin (GNATS administrator)
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Fri Apr 24 04:35:01 1998
>Last-Modified:
>Originator:     Erik E. Fair
>Organization:
International Organization of Internet Clock Watchers
>Release:        NetBSD-current 19980423
>Environment:
	
System: NetBSD digital.clock.org 1.3 NetBSD 1.3 (GENERIC) #0: Thu Jan 1 18:26:28 MET 1998 pk@flambard:/usr/src1/sys/arch/sparc/compile/GENERIC sparc


>Description:
	I am finding the package system documentation somewhat
	lacking. I love the package system theory - programs already
	ported to run on NetBSD that I can just FTP and install
	(or FTP, compile and install). But I have questions:

	1. Where is the catalog of packages (preferably web-based
	or on-system) that gives name, functional description,
	hardware requirements if any, package size (i.e. disk space
	requirements), an a URL for access?

	2. Where is the document that *precisely* outlines the
	steps to set up and maintain the package system as a whole
	(please do not refer me to
	http://www.netbsd.org/Documentation/netbsd/Packages.txt
	because it confusingly contains both instructions for
	installing individual packages and for *making* packages)?

	It would really help if there were a man page distributed
	for this - a general overview, with pointers to other man
	pages that describe local system set up (similar to
	diskless(8)). The man pages for the individual pkg_* commands
	do not help sufficiently.

	Now, please understand that I can (and probably will) UTSL
	at some point to figure this all out myself. However, given
	the purpose of the package system, I shouldn't have to.

>How-To-Repeat:
	Attempt to figure out how the package system works prior to
	the attempt to install a package.

	Fail utterly without resorting to UTSL.

>Fix:
	A clear, unambiguous, precise document must be written that
	explains the operation of the package system as a whole,
	and how to set up one's own system for reception and
	installation of packages.

	In addition, the package system sorely needs a catalog,
	one that can be accessed locally (pkg_info perhaps can be
	adapted to this role), and via the web (i.e. on www.netbsd.org).
	Such a catalog should include as a minimum:

		name of package
		functional description of package (what does it do)
		disk space requirement for package
		special hardware requirements for package (e.g. CD-ROM)
		URL for fetching package

	I also strongly recommend that the package system be given
	prominent play on the home page of the NetBSD web site -
	this is a significant addition to the project because it
	will make the lives of all users of NetBSD much easier.

	This is a really big deal. Let's make the documentation
	right for the audience the package system intends to serve,
	and show off the advantages to the community at large.
>Audit-Trail:
>Unformatted: