[gentoo-dev] RFC: deprecate /usr/share/doc/$PF

[Alexandre Rostovtsev <tetromino@gentoo.org>]

At the moment, Gentoo documentation is supposed to be installed in
/usr/share/doc/$PF. Given the existence of slots, this directory
scheme makes little sense; versioning documentation directories with
$PF seems nearly as silly as would be e.g. appending $PVR to the
filenames of installed man pages. Moreover, /usr/share/doc/$PF results
in a number of problems:

* Since $PF changes on every revision bump and minor version change,
one cannot bookmark a documentation file for a frequently updated
package without using custom portage hooks or scripts that create
stable symlinks to docs.
* Since $PF changes on every revision bump and minor version change,
it's unnecessarily inconvenient to see which documentation files were
added or removed when upgrading a package.
* The package's documentation may be designed primarily for tools and
viewers which expect to load documentation files from a different
location.

I propose the following changes, and will write them up in GLEP form
if the feedback is positive.

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.

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.
   b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT.

3. In EAPI-5 and higher, dodoc/newdoc/dohtml will install documentation in:
   a. If SLOT = "0": /usr/share/doc/$CATEGORY/$PN/<docinto path>
(/usr/share/doc/$CATEGORY/$PN/html for dohtml);
   b. If SLOT != "0": /usr/share/doc/$CATEGORY/$PN-$SLOT/<docinto
path> (/usr/share/doc/$CATEGORY/$PN-$SLOT/html for dohtml).
   Corresponding changes will also have to be made to docompress, and
to the eclasses that currently use /usr/share/doc/${PF} as docdir.

4. In EAPI-0,1,2,3,4, ebuilds may, at the maintainer's discretion,
install documentation in the old /usr/share/doc/$PF location xor in
the new EAPI-5 location.

Answers to anticipated questions:

Q1: Why let docs designed to be viewed with special viewers be
installed outside /usr/share/doc?
A1: To match upstream expectations and to minimize maintenance burden.
This burden can be significant; for example, if documentation for
package A contains explicit links to documentation pages for package
B, then if the documentation pages are not installed where upstream
expects them, those links would have to be adjusted, probably via a
fragile script with untested corner cases.

Q2: Why /usr/share/doc/$CATEGORY/$PN-$SLOT instead of /usr/share/doc/$PN-$SLOT?
A2: To prevent file collisions between packages in different
categories but with identical package and slot names.

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

Q4: Why install slot 0 docs in $CATEGORY/$PN by default instead of
$CATEGORY/$PN-0?
A4: Purely for aesthetics. A vast number of packages in the main tree
are only slot 0 and are unlikely to ever become slotted in the future,
so installing their docs in /usr/share/doc/$CATEGORY/$PN is logical,
pleasing to the eye, and results in shorter directory names.

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.

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.

Q7: Why allow package maintainers to start using the new naming scheme
in earlier EAPIs?
A7: Because /usr/share/doc/$PF really is quite inconvenient for users
wanting to browse API documentation, and package maintainers may wish
to alleviate the users' pain before the EAPI-5 becomes finalized and
support for it is added to the eclasses that the ebuild needs.

-Alexandre.