Subject: Re: CVS commit: pkgsrc/databases
To: Julio M. Merino Vidal <jmmv@menta.net>
From: Michal Pasternak <michal@pasternak.w.lub.pl>
List: tech-pkg
Date: 04/20/2004 18:17:59
Julio M. Merino Vidal [Tue, Apr 20, 2004 at 04:13:13PM +0200]:
> Well... I used an incorrect regexp to look for packages installing pdf's.
> There actually are some of them.  But anyway, my point remains.  Most
> browsers are able to display them, either embedded or opening an external
> application.

In my opinion is doc/html/ and doc/ causes massive confusion, not
only among newbies, I think, that Unix veterans can be confused as well.

Example situation with databases/postgresql-doc, which installs
doc/postgresql _and_ doc/html/postgresql (if that sounds perfectly okay for
you, please read on):

So basically, lets suppose I've just installed postgresql-doc and want to
have a look at it:

	$ cd /usr/pkg/share/doc
	$ ls
	...
	postgresql
	...
	
Ah, there it is, 'postgresql' directory. Let's have a look at it:

	$ cd postgresql
	$ ls
	README FAQ TODO ...
	
Hmm, no HTML documentation? Why did the package take so much space then?
Let's have a look at it...

	$ pkg_info postgresql-doc
	/usr/pkg/share/doc/html/postgresql/...
	...
	/usr/pkg/share/doc/postgresql/...

Ah, the docs are in doc/html/postgresql... but on the other hand - say what?!

				    * * *

I hope you get the whole idea.

If there would be doc/postgresql/html or doc/postgresql/manual, I'd see it,
no problem. If I want to read docs for "foobar", I think "ah, docs for
foobar are in doc/foobar, that's obvious" and x_not_ "ah, it's pkgsrc
package, so HTML docs for foobar are in doc/html/foobar".

There could be even doc/postgresql/html, doc/postgresql/pdf,
doc/postgresql/dvi, there could be a whole bunch of directories _under_ the
one named as the package, and it would be intuitive and ergonomic. 

Many times I've didn't actually remember about the 'html' directory and
thought I haven't installed the docs I needed.

If there is doc/*html*/postgresql together with doc/postgresql, I will
_always_ have a look at doc/postgresql first and I won't find the docs I need.

That's what I think about it. If anyone has something good to say about
share/doc/html, please do so. Except "it's informal pkgsrc standard" or
"many packages use it"... IMO such arguments are about the same, as "I serve
html/ directory with Apache".

IMO, doc/html/ causes confusion and is neither ergonomic nor intuitive.  It
should be removed.

-- 
mp