[ On Sunday, March 28, 2004 at 18:26:02 (+0200), Michal Pasternak wrote: ]
> Subject: Re: New package - epydoc
>
> There was a discussion starting from :
> 
> 	http://mail-index.netbsd.org/tech-pkg/2003/11/06/0004.html
> 	
> ... after which, I don't think, that docs/html is a good idea (all docs
> should go just to docs/).

Indeed using "docs/html" for HTML formatted documents is a really _bad_
idea.  The format of a document can be encoded in its file basename
extension, if necessary.  It is _far_ more important to organize the
location of files by their semantic content -- and we've been doing that
regardless of other types of formatting differences since the beginning
by putting all the document files for a given package in a single
directory under $PREFIX/share/doc which is named after the package.

I.e. HTML is the only stuff someone thought had to be treated in some
special way, and whomever that was, well they were wrong.  You'll find
PostScript, text, troff, PDF, and other types of files all organized
together by package name -- HTML documents must be treated equally.

What's worst of all though is that sometimes there are non-HTML files
found in docs/html which are not, as far as I could tell, linked to by
any of the HTML files.  I guess someone thought it might be bad to split
documentation up into separate directories when on a "normal" (non-pkg)
install there would be no separation -- well that's just one more reason
why segregating HTML files is a _bad_ idea.


> I am using such setup (eg. docs/ only) since a
> some time, all doc packages I do install to share/docs/, not
> share/docs/html, and - belive me - it is much easier to browse such
> documentation, without extra html/ directory.

Same here.  I've simply removed the "html/" prefix from the PLIST files
of any packages I install, undone the unwanted patches, and all's well
and my users are much happier.

-- 
						Greg A. Woods

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