FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Development

 
 
LinkBack Thread Tools
 
Old 12-18-2011, 08:49 PM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

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.
 
Old 12-18-2011, 09:02 PM
Michał Górny
 
Default RFC: deprecate /usr/share/doc/$PF

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
 
Old 12-18-2011, 10:07 PM
Pacho Ramos
 
Default RFC: deprecate /usr/share/doc/$PF

El dom, 18-12-2011 a las 23:02 +0100, Michał Górny escribió:
[...]
> > 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...
>

Maybe this situation could be improved if there was a policy forcing us
to try to use latest EAPI when possible for any package update, that way
we would move faster to latest eapi and even deprecate older eapis
easily
 
Old 12-18-2011, 11:08 PM
Ulrich Mueller
 
Default RFC: deprecate /usr/share/doc/$PF

[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
 
Old 12-18-2011, 11:56 PM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

On Sun, 2011-12-18 at 23:07 +0100, Ch*-Thanh Christopher Nguyễn wrote:
> Alexandre Rostovtsev schrieb:
> > Answers to anticipated questions:
> Q8: SLOT can change after the package was installed. How to handle this
> case?

I think the slotmove should happen without renaming the documentation
directory; silently moving installed files after an emerge --sync
without the user's explicit request seems a bad idea.

This means that a slotmove could result in a future file collision. If
foo-1.0 and foo-2.0 were in slot "1", and >=foo-2.0 was slotmoved from
"1" to "2", then if a user had foo-2.0 installed before the slotmove,
attempting to install foo-1.0 after the slotmove would result in a file
collision in /usr/share/doc/*/foo-1. Such collisions would have to be
resolved with the usual technique of revbumps and blockers.

However, in practice slotmoves that could cause such collisions are
infrequent. Among the 94 slotmoves for 2009 and 2010, I see only five
that would have resulted in potential file collisions in /usr/share/doc
under the proposed scheme: ati-drivers, clojure, vala, libchamplain, and
clutter-gtk. Among the several hundred slotmoves for 2011 so far, I see
*zero* that would have resulted in a collision.

It is possible that I missed some, but even then, I think that less than
10% of slotmoves - probably much less - would have been affected.

-Alexandre.
 
Old 12-19-2011, 12:52 AM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

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.

> 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.

It's not "all over the filesystem"; in practice, the number of locations
I believe is fairly small (/usr/share/gtk-doc and /usr/lib/monodoc for
API documentation, and /usr/share/help, /usr/share/omf,
and /usr/share/doc/HTML for end-user help files are the only ones that I
know of), and adding them to portage's nodoc list seems much easier than
editing hundreds of ebuilds that already install docs there.

Documentation in Gentoo-specific /usr/share/doc subdirectories would not
be able to link to documentation pages in other packages without
fragile, hard-to-maintain scripts - and even with the best scripts,
things would break on package renames. Symlinks could work, but (if the
nodoc situation is resolved) would give package maintainers extra work
for no real benefit.

> Can we please avoid the bloat of another directory level here?
> ${CATEGORY}/${PN} will be even longer than ${PF} in most cases.

The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
x11-terms/terminal:0 and gnustep-apps/terminal:0, or app-misc/beagle:0
and sci-libs/beagle:0, or app-misc/nut:0 and sys-power/nut:0. I could
not think of any better solution than using $CATEGORY/$PN-$SLOT. Do you
have a better proposal that does not rely on $PVR?

> 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.

If everything is to be moved to the new locations, we will need an
eclass-based solution to replace dodoc/dohtml for existing EAPIs.

-Alexandre.
 
Old 12-19-2011, 01:26 AM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

On Sun, 2011-12-18 at 23:02 +0100, Michał Górny wrote:
> What if 'foo' has slot named 'bar', and there is unslotted 'foo-bar'
> package? :P

There are no such examples in the tree. The only ebuilds I could find
with non-numeric slots are various kernel sources, chromium,
google-chrome, beautifulsoup, python-dateutil, b43-firmware,
binutils-apple, gcc-apple, and rep-gtk. If cross-compiling there is also
insight, gdb, newlib, and uclibc, maybe a few more packages from
sys-devel/.

For completeness, I suppose that it wouldn't hurt to add a provision to
allow package maintainers to choose a different documentation directory
if that's required to prevent a file collision.

> > 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.

Fair point. OK, let's kill the "-0"; slot 0 goes in $CATEGORY/$PN only.

> While at this, I think we should somehow move
> the docs for all EAPIs to avoid this, and probably move installed ones
> as well.
>
> [...]
>
> 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...

Then we will also need an eclass-based solution for existing EAPIs to
replace dodoc/dohtml.

-Alexandre.
 
Old 12-19-2011, 01:41 AM
Jeroen Roovers
 
Default RFC: deprecate /usr/share/doc/$PF

On Sun, 18 Dec 2011 21:26:08 -0500
Alexandre Rostovtsev <tetromino@gentoo.org> wrote:

> On Sun, 2011-12-18 at 23:02 +0100, Michał Górny wrote:
> > What if 'foo' has slot named 'bar', and there is unslotted 'foo-bar'
> > package? :P
>
> There are no such examples in the tree. The only ebuilds I could find
> with non-numeric slots are various kernel sources, chromium,
> google-chrome, beautifulsoup, python-dateutil, b43-firmware,
> binutils-apple, gcc-apple, and rep-gtk. If cross-compiling there is
> also insight, gdb, newlib, and uclibc, maybe a few more packages from
> sys-devel/.
>
> For completeness, I suppose that it wouldn't hurt to add a provision
> to allow package maintainers to choose a different documentation
> directory if that's required to prevent a file collision.

For completeness, could you post a list of packages that would benefit
from your proposed changes? It's a little thing called scope.


jer
 

Thread Tools




All times are GMT. The time now is 09:25 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org