[ On Friday, November 7, 2003 at 14:58:50 (+0100), Michal Pasternak wrote: ]
> Subject: Re: hier(7) silent on pkg documentation
>
> Well, for me, it is very predictable, than when I want to read PostgreSQL
> guide with HTML browser, I should go to /usr/pkg/share/doc/html/postgresql.

The uniform, predictable, location of the documentation is very
important.  The file format of the documentation _MUST_ come second, if
ever, and ideally it should be only a filename suffix.

I.e. the use of "/usr/pkg/share/doc/html/postgresql" as a location for
documentation of any kind is VERY wrong and flies in the face of good
human factors design.

If one really needs to separate the HTML-formatted files from any other
files in the documentation then they should, at most, be put in a
sub-directory of the main package "doc" directory:

	$PREFIX/share/doc/${PKGNAME}/html/*.html

However in *BSD unix we've had the ability to use rather long filenames
for almost an eternity now (far longer than HTML has been around!).  If
adding a ".html" suffix onto the end of the names of those files
containing HTML-formatted content isn't more than sufficient for both
man and machine then I must be crazy.  I haven't done a comprehensive
study of all the packages in pkgsrc, but every one of them that I've
encountered which includes any HTML-formatted documentation already uses
a suffix of either ".html" or at least ".htm" on all those files
provided containing HTML-formatted documents.

Note to that I use "${PKGNAME}" in my example pathname -- and I do so
very explicitly.  It really is _necessary_ to include the package
version identifier in the name of the share/doc sub-directory containing
the documentation for that package (unless a further sub-directory is
used in place of the directory name suffix for each potential version of
the package that might be installed simultaneously).  Not all packages
currently in pkgsrc can have multiple versions co-exist on the same
system.  However a good many can, and in the example of something like
postgresql this ability is critical for managing transitions from one
version to another on live production systems.  Sadly postgresql is one
of those pkgsrc modules that is not yet able to support multiple
versions being simultaneously installed, despite the fact that it would
benefit greatly from such an ability.  Even more sad is the fact that
native by-hand installs of postgresql can trivially support multiple
versions co-existing on the same machine.

-- 
						Greg A. Woods

+1 416 218-0098                  VE3TCP            RoboHack <woods@robohack.ca>
Planix, Inc. <woods@planix.com>          Secrets of the Weird <woods@weird.com>