[ On Saturday, November 8, 2003 at 01:16:40 (+0100), Michal Pasternak wrote: ]
> Subject: Re: hier(7) silent on pkg documentation
>
> Greg A. Woods [Fri, Nov 07, 2003 at 10:56:40AM -0500]:
> > [ 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
> 
> Really? Does it come second for man and info? :)

It could, though historical practice has made this the exception that
proves the rule.

However note there's a major difference between the documentation that's
included with, and organized by package, and the documentation that's
"integrated" into the base-OS system documentation in the way that both
add-on manual pages for packages and the browsable forms of texinfo
documents (i.e. the *.info files), included with packages.  In the case
of the latter two the normal built-in indexing and cataloguing
mechanisms make it unnecessary, and indeed less desirable, to locate the
related files in a per-package sub-directory of share/doc since one need
not know where the documents are located in order to find and read them
and because it's a heck of a lot easier to maintain the indexes and
catalogues if those files are 

Remember that manual pages and *.info files are really just private data
files intended for base-OS supplied viewing (and printing) utilities
whereas the "additional" documentation that may be supplied with an
add-on package will rarely be in a format specifically conducive to any
specific operating system's built-in documentation viewing (and
pribting) utilities.  The additional docs will just as likely be in some
(nearly-)directly printable form, such as PostScript, as it will be in
plain ASCII text or HTML.

Of course with a sufficiently advanced HTML publishing system which
could automatically maintain indexes and catalogues in a way similar to
either of how manual pages or info files are maintained, and with a
built-in HTML viewer in the base-OS, the same _could_ hold true for HTML
documents.  However I somehow doubt such features will come to pass in
NetBSD any time soon.

> Most intuituve path for postgresql-docs IMO would be
> share/doc/postgresql/guide.

Why the "/guide" suffix?  How is that intuitive?

Other than that I certainly agree.  :-)

> > 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.
> 
> I can't imagine those benefits.

Perhaps you need the experience of running a 7x24 production database
server through several iterations of upgrades then....  :-)

Currently with pkgsrc-supplied postresql the only safe way to upgrage a
database server is to shut down the server, dump the database using the
old version of the software, pkg_delete postgresql && pkg_add postgresql
to upgrade the software, then re-load the database using the newly
installed version of the software.  Sometimes you need to upgrade
application related software at the same time, and on rare occasions
with major version updates tables may even need re-defining.

In an ideal world you have both old and new releases installed
simultaneously and you migrate the data to the new system without taking
down the old system.  Then once everything tests OK with the new
software you simply stop the old server and restart the new server in
its place -- i.e. with very little downtime and not even the possibility
of any unexpected surprises.

-- 
						Greg A. Woods

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