Gentoo Archives: gentoo-dev

From: Alexandre Rostovtsev <tetromino@g.o>
To: Gentoo Dev <gentoo-dev@l.g.o>, Gentoo PMS <gentoo-pms@l.g.o>
Subject: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
Date: Sun, 18 Dec 2011 21:50:49
1 At the moment, Gentoo documentation is supposed to be installed in
2 /usr/share/doc/$PF. Given the existence of slots, this directory
3 scheme makes little sense; versioning documentation directories with
4 $PF seems nearly as silly as would be e.g. appending $PVR to the
5 filenames of installed man pages. Moreover, /usr/share/doc/$PF results
6 in a number of problems:
8 * Since $PF changes on every revision bump and minor version change,
9 one cannot bookmark a documentation file for a frequently updated
10 package without using custom portage hooks or scripts that create
11 stable symlinks to docs.
12 * Since $PF changes on every revision bump and minor version change,
13 it's unnecessarily inconvenient to see which documentation files were
14 added or removed when upgrading a package.
15 * The package's documentation may be designed primarily for tools and
16 viewers which expect to load documentation files from a different
17 location.
19 I propose the following changes, and will write them up in GLEP form
20 if the feedback is positive.
22 1. If a package's documentation is designed to be accessed by a
23 specific documentation viewer tool, then the package should install
24 the documentation in a location where that tool will look for it (e.g.
25 devhelp expects to find GNOME API documentation in
26 /usr/share/gtk-doc/html, and khelpcenter expects to find KDE handbooks
27 in /usr/share/doc/HTML). This already happens in practice, but some
28 devs had expressed opposition to this (e.g. bug #312363) because it
29 had not been formalized as policy.
31 2. In EAPI-5 and higher, other documentation should be installed under
32 /usr/share/doc:
33 a. if SLOT = "0": in /usr/share/doc/$CATEGORY/$PN by default, xor
34 (at the package maintainer's discretion) in
35 /usr/share/doc/$CATEGORY/$PN-0.
36 b. if SLOT != "0": in /usr/share/doc/$CATEGORY/$PN-$SLOT.
38 3. In EAPI-5 and higher, dodoc/newdoc/dohtml will install documentation in:
39 a. If SLOT = "0": /usr/share/doc/$CATEGORY/$PN/<docinto path>
40 (/usr/share/doc/$CATEGORY/$PN/html for dohtml);
41 b. If SLOT != "0": /usr/share/doc/$CATEGORY/$PN-$SLOT/<docinto
42 path> (/usr/share/doc/$CATEGORY/$PN-$SLOT/html for dohtml).
43 Corresponding changes will also have to be made to docompress, and
44 to the eclasses that currently use /usr/share/doc/${PF} as docdir.
46 4. In EAPI-0,1,2,3,4, ebuilds may, at the maintainer's discretion,
47 install documentation in the old /usr/share/doc/$PF location xor in
48 the new EAPI-5 location.
50 Answers to anticipated questions:
52 Q1: Why let docs designed to be viewed with special viewers be
53 installed outside /usr/share/doc?
54 A1: To match upstream expectations and to minimize maintenance burden.
55 This burden can be significant; for example, if documentation for
56 package A contains explicit links to documentation pages for package
57 B, then if the documentation pages are not installed where upstream
58 expects them, those links would have to be adjusted, probably via a
59 fragile script with untested corner cases.
61 Q2: Why /usr/share/doc/$CATEGORY/$PN-$SLOT instead of /usr/share/doc/$PN-$SLOT?
62 A2: To prevent file collisions between packages in different
63 categories but with identical package and slot names.
65 Q3: Why $PN-$SLOT instead of $PN:$SLOT?
66 A3: So that the directory names are compatible with bash's tab-completion.
68 Q4: Why install slot 0 docs in $CATEGORY/$PN by default instead of
70 A4: Purely for aesthetics. A vast number of packages in the main tree
71 are only slot 0 and are unlikely to ever become slotted in the future,
72 so installing their docs in /usr/share/doc/$CATEGORY/$PN is logical,
73 pleasing to the eye, and results in shorter directory names.
75 Q5: Then why allow package maintainers to alternatively use $CATEGORY/$PN-0?
76 A5: Why not? It will not hurt anything, will not cause file
77 collisions, and some maintainers of a multislotted package, one of
78 which is 0, might prefer to install that slot's docs in
79 $CATEGORY/$PN-0 to prevent a potential impression that docs in
80 $CATEGORY/$PN apply to all of that package's slots.
82 Q6: Why can't the dodoc/dohtml path be changed before EAPI-5?
83 A6: Because the path where dodoc and dohtml install files is part of
84 the PMS. Portage can't just change it on its own. A possible
85 workaround for current EAPIs is adding new-style dodoc/dohtml
86 analogues to an eclass.
88 Q7: Why allow package maintainers to start using the new naming scheme
89 in earlier EAPIs?
90 A7: Because /usr/share/doc/$PF really is quite inconvenient for users
91 wanting to browse API documentation, and package maintainers may wish
92 to alleviate the users' pain before the EAPI-5 becomes finalized and
93 support for it is added to the eclasses that the ebuild needs.
95 -Alexandre.


Subject Author
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF "Michał Górny" <mgorny@g.o>
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF "Chí-Thanh Christopher Nguyễn" <chithanh@g.o>
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF Ulrich Mueller <ulm@g.o>
Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF "Andreas K. Huettel" <dilfridge@g.o>