On Fri, 7 Nov 2003 14:18:52 -0500 (EST), "Greg A. Woods" <woods@weird.com>
wrote:
> [ On Thursday, November 6, 2003 at 20:56:33 (-0500), James K. Lowden
> wrote: ]
> 
> > > All non-manual page documentation should go uniformly into:
> > > 
> > > 	$PREFIX/share/doc/$PKGNAME
> > 
> > I was afraid a many-packaged system would become unwieldy without a
> > hierarchy.  You don't think that's a problem?
> 
> In any case I'm not sure using the package categories to rather
> arbitrarily reduce the number of sub-directories per directory is of any
> help.  It's difficult to discover which "category" a package belongs to
> after it is installed ('pkg_info -B pkgname | fgrep PKGPATH=' does the
> trick at the moment, but that's a very-less-than-obvious trick)

Best to begin by saying, Greg, that I now know from experience it's much
more fun agreeing with you than not. (!)  :-)  'Cause I've done the other
and prefer this.  

I'm persuaded that $PREFIX/share/doc/$PKGNAME is fine, mostly because the
number of installed packages is 1:10 to available packages, and a
couplahundred entries in a directory is fine.  (For the record, I use "ls
-d /usr/pkgsrc/*/*foo*" all the time to find packages.)  

I also like your refinement of using the complete $PKGNAME to support
different versions of a package.  I have another suggestion, because a
version in directory name is impossible to remember (and pretty hard to
care about).  

Suppose the real directory name were $PREFIX/share/doc/.$PKGNAME (note
'.'), and there were a symbolic name for humans (similar to .so names). 
So
(putatively):

$ ls -la /usr/pkg/share/doc/      
...
drwxr-xr-x  2 root  wheel  512 Nov  7 23:13 .bash-2.04
lrwxr-xr-x  1 root  wheel   10 Nov  7 23:16 bash -> .bash-2.04

> I like Alan's suggestion of including the location of any additional
> documentation in the manual page(s)

Me too.  

One thing that separates NetBSD from various Linuxa I've installed is that
NetBSD takes its man pages seriously.  It's not unusual, as Tom Jones
might say, to find on a Red Hat system man pages for uninstalled binaries,
and binaries lacking man pages.  NetBSD rightly considers that a bug.  Man
pages might be unfashionable in this DocBook age, but they're no less
useful or handy.  

> It would also make sense to include in the default "pkg_info" output
> some indication of what further documentation is available on the local
> system for each package.  Sometimes this is done in a MESSAGE file, and
> sometimes it's done in the DESCR file, but ideally it should be a
> separate "field" in the database so that it can be uniformly queried.

I have no opinion on this.  I don't know enough about the work involved.  

> As others have said before, and we both say now, xpkgwedge should have
> been the default for all of pkgsrc from the beginning.  Unfortunately it
> wasn't.  It's not a "trivial" thing to make work automatically either,
> especially since there are potential issues with upgrades and
> re-installs of the base-OS X11 (or, imagine, an add-on X11 :-).

The trivial thing, IMHO, would be the placement in the base of
/usr/pkgsrc/makefile (little 'm').  "make" would require $CVSROOT, and
checkout the skeleton, install the tools ... and xpkgwedge.  Then "mv
makefile Makefile.bootstrap" to make way for pkgsrc's Makefile.  The naïve
user would benefit and the traditionalist wouldn't have much to undo.  

But I might have missed your point.  If you're saying xpkgwedge has
pitfalls that will bite sooner or later, naïve or not, then OK.  I could
live with symlinks in /usr/pkg/share/doc pointing to the real directories
(cf. your point about /usr/pkg/etc).  I'd still have to look in only one
place.  

> > > Personally I think hier(7) should be entirely silent on /usr/pkg,
> > > save for this one sentence:
> > > 
> > > 	/usr/pkg	- mirrors the structure of /usr with the
> > > 			  addition of /etc as /usr/pkg/etc.
> > 
> > Hear, hear!  /usr/pkg/var, while we're at it.
> 
> Well, I won't go that far -- which is why I explicitly didn't mention
> it.

Understood.  No problem.  Let's stick with documents.  hier(7) might say:

/usr/pkg	- mirrors the structure of /usr with the
		  addition of /etc as /usr/pkg/etc.

/usr/pkg/doc	- documentation of packages in formats other than man and
info pages.  

> Let /var be /var -- it contains machine specific, local, files

Good point.  

+++

From the response so far, it sounds it's (basically) agreed that
rationalizing package documentation would be a Good Thing.  Absent a
protest, I'd like to hear from Alister & Co.  I can submit a patch for
hier(7).  How to go from there?  

--jkl