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

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

On Wed, 2010-08-25 at 14:55 +1000, Ben Finney wrote:
> On 27-Sep-2003, Josip Rodin wrote:
> > Some proposed mandating that -doc package contents is placed into
> > /usr/share/doc/<package>/, and that the administrivia such as
> > copyright and changelog stays in /usr/share/doc/<package>-doc/. This
> > sounds good to me because it has a sort of an internal logic, the
> > -doc suffix only exists because of packaging, it's actually the docs
> > for <package>. Plus, it's shorter, less to type.
> There seems to be consensus on doing this, so I've made a patch
> (attached to this message) which implements that recommendation.

Hi Ben,

Thanks for the patch, but since that was from 2003 I wonder if it
deserves a little more discussion now, before we apply it.

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

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

While both proposals would move the <package>-doc content to
under /usr/share/doc/<package>, I would prefer to see a reduction in the
number of directories under /usr/share/doc - admittedly on my own system
this would only be around 1% reduction.

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.

I think it particularly confuses people when the -doc package first
splits out of the original package, since the docs get moved away at
that point.

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

					Andrew McMillan.
andrew (AT) morphoss (DOT) com                            +64(272)DEBIAN
            Change your thoughts and you change your world.

Attachment: signature.asc
Description: This is a digitally signed message part

Reply to: