cube@cubidou.net [Tue, Apr 20, 2004 at 06:53:40PM +0200]:
> > IMO, doc/html/ causes confusion and is neither ergonomic nor intuitive.  It
> > should be removed.
> 
> Then what about those hideous and confusing 'man' and 'info' directories?

First, please be so kind and put your sarcasm into that dark place where it
belongs.

man and info are both a documentaiton systems and comparing them to
share/doc (which is just a *path* where files reside) is a mistake:

 * man(1):

   In 99% cases of man usage, you just type "man foobar" or "man 5 foobar"
   and you don't care about the actual path - and it can be either
   /usr/share/man/man?, /usr/pkg/X11R6/man, /usr/pkg/share/man, perhaps
   many other paths. As man(1) does the searching for you, you don't care
   about the path, so the path can be really anything. MANPATH setting
   does that.

 * info(1):
 
   Same issue with path, info(1) will look in INFOPATH, which can be 
   /usr/share/info, /usr/pkg/info, and other settings. Typing just plain
   "info" will display the index of all documentation (no matter what the
   paths are!)
   
As you can clearly see, both man and info can hold their files _anywhere_ on
the hard drive, while leaving _same_ end-user interface.

You don't have to type "info -f /opt/share/doc/info/foobar", just setup
INFOPATH for all users and "info foobar" will do. No matter, where foobar
is. It is pretty the same for man.

Thus, comparing man and info to share/doc/html, where you _do_ have to know
the paths, is a mistake. 

I hope you agree.

> I don't really see what is confusing here.  I don't access share/doc/$PKGBASE
> and share/doc/html/$PKGBASE the same way.

Strange. No matter if I access share/doc via "cd", via "konqueror" or with
Opera, I _always_ have to wonder for a while, was that HTML docs I was
looking for, or not? In many cases I have to check both directories.

> I expect to find mostly vi-friendly documentation inside share/doc/$PKGBASE,

If you like reading docs via "vi" or "less" because they work on text
terminals (no other reason comes to my mind), perhaps you could also try
"links", "lynx", "w3m", "w3" in emacs/xemacs or that nice line-mode (not
fullscreen) utility to read HTML docs, whose name I've forgot.

> Now, the confusion might only be a documentation issue, as I, for one, am
> aware of the html directory, but it might be a matter of circumstances.

Of course, you're aware, I am aware, 99.9% of tech-pkg@ subscribers is
aware. The point is, that some people don't think, that it is a good idea to
have doc/ and doc/html/.

... and I *still* haven't heard a good pro-doc/html/ argument.

> Let's just document it.  I find 'man packages' rather poorly advertised,
> too, whereas it really is useful in case of a package duplicating
> something in base.  And not getting the manpage matching the used version
> *is* confusing.

Of course, share/doc must be documented in hier(7) and in Packages.txt, but
first let's perhaps decide if we really want to use doc/html/. 

Perhaps to cut the endless discussions, currently active pkgsrc developers
could do some voting, which version to choose, then document it, then I
promise to STFU - even if you decide to use doc/html/, but I belive you will
choose the good way, not the doc/html way.

Anyway, who created share/doc/html/ first and what was his/hers reasoning?