Re: fixing up /usr/doc

[Martin Schulze <joey@carelia.infodrom.north.de>]

Zack Brown wrote:
> /usr/doc is virtually unusable because of the many bogus entries it has. The
> directory listing takes a long time to even start to display, and most of
> the entries are pretty much empty anyway. why not make /usr/doc a place
> where real documentation (and *only* real documentation) can be found. Right
> now users have to sift through endless stubs to get to the real stuff.
> 
> Why not have a /usr/doc/stubs directory, where stubs can go until they get
> some real docs to put in them?

Please let me understand your concerns.

 1. You think /usr/doc contains so "many bogus entries".  Can you
    elaborate on this please?  Which entries are bogus?  They are
    probably bugs in some packages.

 2. The directory listing takes long.  Well, this is due to the current
    way Linux ext2fs stores directory information.  I've got the
    impression from Ted Tytso that ext3 will be different.

    In either way, what can we do about this?  /usr/doc contains
    regular and additional information for each package.  This reflects
    a canonical way to access more information than manpages and info
    files can provide.

    The most important files for devlopers are the copyright and changelog
    files in /usr/doc/<package>/.  The most important files for uses are
    all other files.  There is a canonical way to access these files.
    It is well known and that is good.  However I have to admit that
    several copyright files lack source URLs - which should be reported
    as bug.

 3. You say "most of the entries are pretty much empty".  This is a bug.
    Please report it against the specific package.

 4. "Right now users have to sift through endless stubs".  Can you
    please elaborate on this?  The correct way to access documentation
    is 1st manpages, 2nd info files, 3rd /usr/doc/<package>/* .

I've always found /usr/doc quite useful if packages where they provided
some additional files other than the mandatory ones.  If no additional
information is provided in /usr/doc/*/ often there is none provided by
the package.  If otherwise this is a bug and the maintainer needs to
be informed that he forgot to provide all information.

Regards,

	Joey

-- 
If you come from outside of Finland, you live in wrong country.
	-- motd of irc.funet.fi

Please always Cc to me when replying to me on the lists.