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

Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/



Andrew McMillan <andrew@morphoss.com> writes:

> My personal preference would be to encourage -doc packages to install
> their files into /usr/share/doc/<package>/docs - including their
> internal administrivia.

That would break Lintian, apt-listchanges, probably the DAK processing
scripts, and anything else that looks at copyright and changelog in binary
packages.  I don't think it's worth it to make that change.

> While this is not current practice, I'm not convinced that current
> practice has evolved into what was suggested in 2003 either.

Right now, I'm seeing a real mix of behavior, with some packages
installing all the documentation into the -doc package's /usr/share/doc
(probably in part because that's easier) and others installing it into the
parent package, some with symlinks and some without.  As a result, right
now one cannot easily find the documentation in any standardized place.

> I also remember as a user hunting for these documents the first time or
> two when I had installed the -doc package and it slowly dawning on me
> that they weren't anywhere in /usr/share/doc/<package>, and I think that
> breaks the principal of least surprise, for everyone except long-time,
> hard-core Debianista.

Yeah, that's what Ben's writeup would fix, and I agree that's worth
fixing.

> Those points are justifications for both proposals, of course, and I
> guess that one reason for retaining the administrivia
> in /usr/share/doc/<package>-doc might be that there are tools that
> expect to find it there.  Is that the case?

Yup.

> I don't think I ever do more than refer to them by hand, and either
> proposed change can probably be codified in some small number of
> scripts.

I don't think the change proposed here requires changing any scripts,
although it will require changing a bunch of packages (and a change to
debhelper to make it easier to install docs into the right place would be
useful).

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Reply to: