Re: fixing up /usr/doc
On Thu, 24 Dec 1998, Chris Waters wrote:
> Zack Brown wrote:
> > On 24 Dec 1998, Ben Gertzfield wrote:
>
> > > The point of /usr/doc/packagename/ is not only the docs, but as you
> > > must have noticed, the copyright and changelog information.
>
> More precisely, the point of /usr/doc/packagename is NOT the docs! It
> is primarily for package information like copyright and packaging notes,
> and a place to store *supplemental* documentation. The proper place for
> user documentation on a Debian system is in /usr/man.
>
> > I know... but shouldn't that information be somewhere else? I mean, it
> > renders the directory useless. If you have to have copyright information
> > in /usr/doc, then at least put the real docs somewhere else so people
> > can get to them. it's a real pain wading through that directory looking
> > for docs.
>
> You shouldn't *be* wading through that directory looking for docs.
> That's not what it's for.
>
> Every program and library is supposed to contain at least one man page.
> The man page *should* mention any supplemental documentation that's
> available. Failure to do so should probably be considered a bug. Info
> and html docs should likewise be available without digging around in
> /usr/doc.
>
> Basically, you shouldn't be looking in usr/doc/packagename unless you've
> been directed to do so by other documentation -- and that should tell
> you *which* directory, so you don't have to hunt around. So,
> complaining that it's not productive to hunt around rather misses the
> point. Complaining that some packages encourage you to do so, by e.g.
> not providing adequate man pages, would be rather more to the point.
> I'd join you in that complaint.
In that case, I suggest splitting supplemental docs out of /usr/doc, and
putting them somewhere dedicated to supplemental docs.
I agree completely that man pages should tell the location of supplemental
docs, but are you saying that man pages *and only manpages* should be the
way to access those supplemental docs? Why put such an unnecessary
restriction on users? I, for one, often feel like poking around my system
without necessarily knowing what I'm poking around *for*. I love finding
directories filled with wonderful sources of information that I can peruse
at my leisure. And right now, /usr/doc is one of those sources and it is
impossible to use!
Please, please, PLEASE! don't let /usr/doc remain a beurocratic black box
where you have to know what you want before you look inside.
The /etc directory, for instance, is really great because all the
configuration files are right there, well organized. I can explore happily
for hours, tweaking things I never knew existed until I looked around. /bin,
/sbin, /usr/bin, and /usr/sbin are equally great because 99% of my
executables are right there, ready to tinker with.
But if I want to see what has interesting documentation, /usr/doc has over
800 entries, most of which are not documentation. What am I supposed to do?
Read every man page and look for strings that start /usr/doc? Or maybe cd
into each of those directories (as I've tried from time to time) hoping to
get lucky?
It's not such a sin, to take all those tasty docs and put them someplace I
can get to them. Keep /usr/doc for copyright and packaging info if you must,
but can't there be some compromise about the rest?
Zack
> --
> Chris Waters xtifr@dsp.net | I have a truly elegant proof of the
> or xtifr@debian.org | above, but it is too long to fit into
> http://www.dsp.net/xtifr | this .signature file.
>
>
> --
> To UNSUBSCRIBE, email to debian-devel-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
>
Reply to: