On Thu, 6 Nov 2003 12:11:09 +0100, Michal Pasternak
<michal@pasternak.w.lub.pl> wrote:
> James K. Lowden [Thu, Nov 06, 2003 at 03:19:11AM -0500]:
> 
> Take postgresql for example.
> 
> It comes with just a few files (like README, FAQ, some config examples
> installation notes) - such files go to /doc/.
> 
> But, when you install a whole bunch of HTML documentation files, that
> describes PostgreSQL from user, programmer and administrator point of
> view - PostgreSQL guide - such files go to /doc/html/

My proposal is that all postgresql documentation would be in a postgresql
tree, rooted at /usr/pkg/share/database or /usr/pkg/share/doc.  If
postgresql docs are normally split up, IMHO that should happen inside that
tree.  But whether the postgresql docs are one tree or two, their location
would be predictable.  

> I don't think it's really a bad. On Debian it's quite the same, you
> have directories like "postgresql" and "postgresql-doc" in such case.

I don't find that compelling.  Just because everyone's stumbling in a fog
or no one can forge a consensus isn't a reason for us to (not) do
anything.  

> Honestly, I'd rather like to see some utility (heck, let it be in
> basesystem and let it be BSD-licensed), that would automatically index
> all available documentation on my system, than spend time on correcting
> pkgsrc entries ;)

I have utilities: ls, find, grep.  I wouldn't mind more, something like
you're suggesting.   Indexing the documetation is orthogonal to organizing
it, and surely no substitute.  

> > My suggestion is that /usr/pkg/share hold the documentation in a tree
> > mimicking /usr/pkgsrc.  IOW,
> 
> Doesn't sound reasonable. Why then whole /usr/pkg shouldn't mimic pkgsrc
> tree? You could have /usr/pkg/ghostscript/bin|share|lib|doc... 

Not at all.  If we can get away with /usr/pkg/share/doc as a single root,
I'm all for it.  If /usr/pkg/share/doc looked like

archivers    cross        fonts        math         pkglocate    time
audio        databases    games        mbone        pkgtools     wm
benchmarks   devel        graphics     meta-pkgs    print        www
biology      distfiles    ham          misc         security     x11
cad          doc          inputmethod  mk           shells
chat         editors      lang         net          sysutils
comms        emulators    licenses     news         templates
converters   finance      mail         parallel     textproc

So if you want bash documentation, for instance, you'd look in
/usr/pkg/share/doc/shells/bash.  

That would be good protection against the package explosion of 2006.  ;-)

> PostgreSQL doc path becomes
> /usr/pkg/share/databases/postgresql/html, which is a bit longer (and
> harder to find), than current /usr/pkg/share/doc/html/postgresql ;)

On the contrary, it's easier to find!  What's more important: that
postgresql docs are in html, or that "html" docs include postgresql?  Get
the package *name* up the tree; move the documentation's form *down*.  

--jkl