Subject: Re: CVS commit: pkgsrc/databases
To: Volker A. Brandt <>
From: Greg A. Woods <>
List: tech-pkg
Date: 04/25/2004 16:38:59
Volker A. Brandt [Wed, Apr 21, 2004 at 06:52:36PM +0200]:
> Good point.  This brings me to the following idea:
> Why not emulate the way info works for the html format?  There is
> a central directory file (called "dir") in every info directory.

Bad point actually.

There's nothing "special" about HTML documentation, or rather about the
HTML parsing capability of browsers (and servers) that can read (and
serve) HTML files -- those browsers (and servers) can also all read (and
serve) many other file formats as well, not just HTML files.

Also, as for having a "descriptive master index" of installed
documentation, well while a such a thing would be nice to have, there's
no fundamental need for one since all browsers (and servers) can present
directory listings.  If the .../share/doc directory is organized by
package name then it's still very easy for users of web browsers to find
the documentation for a given package.  Of course if the README.html
file generated in pkgsrc were installed in .../share/doc/${PKGNAME}.html
and if it contained a link to the .../share/doc/${PKGNAME}/ directory
then it might be easier for some folks to browse the installed
documentation without a master .../share/doc/index.html being kept
up-to-date with every installed/de-installed package.

Even if there were a supplemental master index for installed documents
there's no need for segregating the HTML files from text (or PS or PDF
or other such files) -- and indeed every reason not to segregate them,
since if your goal is to browse documentation using a "web browser"
(either directly or through a web server) then you should want to see
all documents in all viewable formats, not just the HTML files and
whatever other files they directly link to.

Unix-style manual pages are segregated for historical reasons (and to
make indexing and accessing them with "man" somewhat easier).

Info files are segregated because they're one special output format
generated from a source file that can also be used to generate ordinary
text files or typeset output suitable for printing.  Info files are also
not normally viewable by common "web browsers".

I.e. Texinfo documentation could (and probably should) be installed in
the .../share/doc/$PKGNAME/ directory in text, dvi, and perhaps
PostScript and/or PDF format (as well as being installed in the info
directory in info format).

						Greg A. Woods

+1 416 218-0098                  VE3TCP            RoboHack <>
Planix, Inc. <>          Secrets of the Weird <>