[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: fixing up /usr/doc

Peter S Galbraith wrote:

> 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.

> Then we should have a tree called

> /usr/doc--we-really-mean-it/

Why this fascination with a tree of documentation?  Why not something
that's more easily accessible?  Browsing through hundreds of
subdirectories may be enjoyable for some hackers, but any hacker who has
been playing with Debian for long knows to use the dpkg --listfiles
command to see what files come with a package, so we don't actually need
a fixed location like /usr/doc for them.  And as for newbies, they
really need something a little simpler in any case.

A change like that would require modifying EVERY SINGLE DEBIAN PACKAGE
for not much gain in user-friendliness.

> It has also bothered me that Debian packages have files called
> `copyright' but no `license' files.

Now, this I can sympathize with.  However, it again requires modifying
every single Debian package.  I think that's a bit extreme.

It is currently a bug not to have a man page.  It is *also* a bug to use
the "undocumented" man page as a man page.  I think it should be a bug
to have supplemental documentation in /usr/doc that's not mentioned in
the man page (obviously "undocumented" qualifies, since it doesn't
mention that, but any package using "undocumented" is buggy by
definition).  Then we can assure that all packages either:

a) mention any supplemental docs in their man pages or
b) have a bug.

The doc-base package may offer a way out of this problem -- I haven't
really looked at it.  If so, that's great, but other solutions that
involve massive amounts of work, and offer very little reward, do NOT
have my support.  (I hate browsing /usr/doc even though I know what I'm
doing, and I'd hate it even if only one in ten packages had
/usr/doc/packagename entries.)

Making /usr/doc a little smaller is NOT helping to make our system
easier to use IMO.  At least, not enough to justify the amount of work

As I say, I haven't really looked at the doc-base package yet, but if
it's a bug to have documentation not registered with doc-base, then I'd
consider that an acceptable replacement for my suggestion above (bug not
to mention supplemental documentation in the man page).
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.

Reply to: