Subject: Re: CVS commit: pkgsrc/databases
To: Julio M. Merino Vidal <firstname.lastname@example.org>
From: Michal Pasternak <email@example.com>
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
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
Ah, there it is, 'postgresql' directory. Let's have a look at it:
$ cd postgresql
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
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.