* [gentoo-pms] RFC: deprecate /usr/share/doc/$PF
@ 2011-12-18 21:49 Alexandre Rostovtsev
2011-12-18 22:02 ` [gentoo-pms] Re: [gentoo-dev] " Michał Górny
2011-12-19 0:08 ` Ulrich Mueller
0 siblings, 2 replies; 4+ messages in thread
From: Alexandre Rostovtsev @ 2011-12-18 21:49 UTC (permalink / raw
To: Gentoo Dev, Gentoo PMS
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.
^ permalink raw reply [flat|nested] 4+ messages in thread
* [gentoo-pms] Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
2011-12-18 21:49 [gentoo-pms] RFC: deprecate /usr/share/doc/$PF Alexandre Rostovtsev
@ 2011-12-18 22:02 ` Michał Górny
2011-12-19 0:08 ` Ulrich Mueller
1 sibling, 0 replies; 4+ messages in thread
From: Michał Górny @ 2011-12-18 22:02 UTC (permalink / raw
To: gentoo-dev; +Cc: tetromino, Gentoo PMS
[-- Attachment #1: Type: text/plain, Size: 2747 bytes --]
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@gentoo.org> 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
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 316 bytes --]
^ permalink raw reply [flat|nested] 4+ messages in thread
* [gentoo-pms] Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
2011-12-18 21:49 [gentoo-pms] RFC: deprecate /usr/share/doc/$PF Alexandre Rostovtsev
2011-12-18 22:02 ` [gentoo-pms] Re: [gentoo-dev] " Michał Górny
@ 2011-12-19 0:08 ` Ulrich Mueller
2011-12-19 1:03 ` Alexandre Rostovtsev
1 sibling, 1 reply; 4+ messages in thread
From: Ulrich Mueller @ 2011-12-19 0:08 UTC (permalink / raw
To: gentoo-dev, gentoo-pms
[Why are there different Reply-To: headers in -dev and in -pms MLs?
Following up to both lists.]
>>>>> On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote:
> At the moment, Gentoo documentation is supposed to be installed in
> /usr/share/doc/$PF. [...]
> 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.
How do you handle FEATURES="nodoc" if you spread the documentation all
over the filesystem? Should Portage learn about all the special cases?
IMHO it would make more sense to leave the documentation under
/usr/share/doc and either configure the documentation viewer to find
it there, or (if that's not possible) create symlinks.
> 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.
Can we please avoid the bloat of another directory level here?
${CATEGORY}/${PN} will be even longer than ${PF} in most cases.
Or, to say it in your own words: "${CATEGORY}/${PN} seems nearly as
silly as would be e.g. prepending ${CATEGORY} to the filenames of
installed man pages." ;-)
> [...]
> 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.
If we change our policy, then we should move everything to the new
location (with a transition period of course). It would be very
inconvenient for users if they had to search two different places
for documentation.
Ulrich
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [gentoo-pms] Re: [gentoo-dev] RFC: deprecate /usr/share/doc/$PF
2011-12-19 0:08 ` Ulrich Mueller
@ 2011-12-19 1:03 ` Alexandre Rostovtsev
0 siblings, 0 replies; 4+ messages in thread
From: Alexandre Rostovtsev @ 2011-12-19 1:03 UTC (permalink / raw
To: gentoo-pms
On Mon, 2011-12-19 at 01:08 +0100, Ulrich Mueller wrote:
> [Why are there different Reply-To: headers in -dev and in -pms MLs?
> Following up to both lists.]
I apologize for the mess; I had intended to bring the question up before
a wider audience, but failed to think through the consequences of two
mailing lists ending up in the reply-to.
For the sake of keeping discussion in one thread, I ask that further
replies should be made to gentoo-dev, not gentoo-pms.
-Alexandre
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2011-12-19 1:04 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-12-18 21:49 [gentoo-pms] RFC: deprecate /usr/share/doc/$PF Alexandre Rostovtsev
2011-12-18 22:02 ` [gentoo-pms] Re: [gentoo-dev] " Michał Górny
2011-12-19 0:08 ` Ulrich Mueller
2011-12-19 1:03 ` Alexandre Rostovtsev
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox