Gentoo Logo
Gentoo Spaceship

Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-pms
Lists: gentoo-pms: < Prev By Thread Next > < Prev By Date Next >
To: gentoo-dev@g.o
From: Michał Górny <mgorny@g.o>
Subject: Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Sun, 18 Dec 2011 23:02:05 +0100
I basically agree, it's quite a great idea. Just a few comments though.

On Sun, 18 Dec 2011 16:49:38 -0500
Alexandre Rostovtsev <tetromino@g.o> wrote:

> * The package's documentation may be designed primarily for tools and
> viewers which expect to load documentation files from a different
> location.

That's why I, for instance, use gtk-doc in my libraries. It's just that
it has its standard install procedures and locations.

> 1. If a package's documentation is designed to be accessed by a
> specific documentation viewer tool, then the package should install
> the documentation in a location where that tool will look for it (e.g.
> devhelp expects to find GNOME API documentation in
> /usr/share/gtk-doc/html, and khelpcenter expects to find KDE handbooks
> in /usr/share/doc/HTML). This already happens in practice, but some
> devs had expressed opposition to this (e.g. bug #312363) because it
> had not been formalized as policy.

Agree. But that's outside of the GLEP/PMS scope; just an internal policy
should fine, I think.

> 2. In EAPI-5 and higher, other documentation should be installed under
> /usr/share/doc:
>    a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor
> (at the package maintainer's discretion) in
> /usr/share/doc/$CATEGORY/$PN-0.

I'd rather not see that -0 there.

>    b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT.


> Q3: Why $PN-$SLOT instead of $PN:$SLOT?
> A3: So that the directory names are compatible with bash's
> tab-completion.

What if 'foo' has slot named 'bar', and there is unslotted 'foo-bar'
package? :P

> Q5: Then why allow package maintainers to alternatively use
> $CATEGORY/$PN-0? A5: Why not? It will not hurt anything, will not
> cause file collisions, and some maintainers of a multislotted
> package, one of which is 0, might prefer to install that slot's docs
> in $CATEGORY/$PN-0 to prevent a potential impression that docs in
> $CATEGORY/$PN apply to all of that package's slots.

This will make the policy less clear, and documentation locations more
enigmatic for users. While at this, I think we should somehow move
the docs for all EAPIs to avoid this, and probably move installed ones
as well.

> Q6: Why can't the dodoc/dohtml path be changed before EAPI-5?
> A6: Because the path where dodoc and dohtml install files is part of
> the PMS. Portage can't just change it on its own. A possible
> workaround for current EAPIs is adding new-style dodoc/dohtml
> analogues to an eclass.

I think some of devs agree we should be allowed to fix past mistakes
without waiting another 20 years till the tree is migrated to a new

Best regards,
Michał Górny
signature.asc (PGP signature)
RFC: deprecate /usr/share/doc/$PF
-- Alexandre Rostovtsev
Lists: gentoo-pms: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
RFC: deprecate /usr/share/doc/$PF
Next by thread:
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Previous by date:
RFC: deprecate /usr/share/doc/$PF
Next by date:
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF

Updated Jul 18, 2012

Summary: Archive of the gentoo-pms mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.