Gentoo Archives: gentoo-pms

From: "Michał Górny" <mgorny@g.o>
To: gentoo-dev@l.g.o
Cc: tetromino@g.o, Gentoo PMS <gentoo-pms@l.g.o>
Subject: [gentoo-pms] Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Sun, 18 Dec 2011 22:01:38
Message-Id: 20111218230205.4df86707@pomiocik.lan
In Reply to: [gentoo-pms] RFC: deprecate /usr/share/doc/$PF by Alexandre Rostovtsev
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 EAPI... -- Best regards, Michał Górny

Attachments

File name MIME type
signature.asc application/pgp-signature