From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from pigeon.gentoo.org ([208.92.234.80] helo=lists.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from ) id 1RcOd7-0000wN-MA for garchives@archives.gentoo.org; Sun, 18 Dec 2011 21:50:49 +0000 Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 3E6B521C1F9; Sun, 18 Dec 2011 21:50:39 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by pigeon.gentoo.org (Postfix) with ESMTP id 6298D21C05B; Sun, 18 Dec 2011 21:50:02 +0000 (UTC) Received: from mail-vx0-f181.google.com (mail-vx0-f181.google.com [209.85.220.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits)) (No client certificate requested) (Authenticated sender: tetromino) by smtp.gentoo.org (Postfix) with ESMTPSA id 72A901B403A; Sun, 18 Dec 2011 21:50:01 +0000 (UTC) Received: by vcbfk26 with SMTP id fk26so3088754vcb.40 for ; Sun, 18 Dec 2011 13:49:59 -0800 (PST) Received: by 10.220.231.136 with SMTP id jq8mr8301656vcb.18.1324244999223; Sun, 18 Dec 2011 13:49:59 -0800 (PST) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 Received: by 10.52.161.227 with HTTP; Sun, 18 Dec 2011 13:49:38 -0800 (PST) From: Alexandre Rostovtsev Date: Sun, 18 Dec 2011 16:49:38 -0500 Message-ID: Subject: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF To: Gentoo Dev , Gentoo PMS Content-Type: text/plain; charset=UTF-8 X-Archives-Salt: 12c2af88-35c3-4238-89ae-32ab1a5109ba X-Archives-Hash: 3fcc9ca1c75826798c6f5e36c6f33c18 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/ (/usr/share/doc/$CATEGORY/$PN/html for dohtml); b. If SLOT != "0": /usr/share/doc/$CATEGORY/$PN-$SLOT/ (/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.