$ qfile /usr/share/gtk-doc/ x11-libs/gtk+ (/usr/share/gtk-doc) x11-libs/pango (/usr/share/gtk-doc) x11-libs/cairo (/usr/share/gtk-doc) gnome-base/libglade (/usr/share/gtk-doc) gnome-base/librsvg (/usr/share/gtk-doc) app-i18n/enca (/usr/share/gtk-doc) app-text/poppler-bindings (/usr/share/gtk-doc) media-gfx/gimp (/usr/share/gtk-doc) media-libs/swfdec (/usr/share/gtk-doc) media-libs/gst-plugins-base (/usr/share/gtk-doc) media-libs/gstreamer (/usr/share/gtk-doc) media-libs/libgpod (/usr/share/gtk-doc) sys-apps/hal (/usr/share/gtk-doc) net-libs/libsoup (/usr/share/gtk-doc) dev-libs/glib (/usr/share/gtk-doc) dev-libs/dbus-glib (/usr/share/gtk-doc) dev-libs/atk (/usr/share/gtk-doc) dev-libs/liboil (/usr/share/gtk-doc) dev-python/pygtk (/usr/share/gtk-doc) dev-python/pygobject (/usr/share/gtk-doc) gnome-extra/libgsf (/usr/share/gtk-doc)
Please open seperate bugs for each ebuild and let them block this bug.
unfortunately you got it wrong, USE="-doc" in gnome related packages means you don't rebuild docs, not that you don't install docs. You could come and discuss this on #gentoo-desktop, it would have spared you from filling those bugs.
(In reply to comment #3) > unfortunately you got it wrong, USE="-doc" in gnome related packages means you > don't rebuild docs, not that you don't install docs. Is this written anywhere? I could only find: *) 'doc' global USE flag -> Adds extra documentation (API, Javadoc, etc) *) media-libs/swfdec:doc -> Build documentation *) sys-apps/hal:doc -> Generates documentation that describes HAL's fdi format. The first two descriptions are fairly generic... Furthermore, I cannot see why you should consider packages like app-text/poppler-bindings, media-libs/swfdec, sys-apps/hal and x11-libs/cairo as "gnome-related" packages.
And what's the point in rebuilding docs if they are already in the tarball?
(In reply to comment #4) > Furthermore, I cannot see why you should consider packages like > app-text/poppler-bindings, media-libs/swfdec, sys-apps/hal and x11-libs/cairo > as "gnome-related" packages. > oh I don't know, maybe because they are related... (In reply to comment #5) > And what's the point in rebuilding docs if they are already in the tarball? because it provides crosslinking between docs which is highly appreciated when developping. Now if you want to discuss this, please forward to gentoo-dev mailing list as bugzilla is not the place for debate, betelgeuse already posted something following this bug report.
Simply use INSTALL_MASK=/usr/share/gtk-doc if you don't like gtk-doc's...
Quoting Mart Raudsepp from gentoo-dev ML: (http://archives.gentoo.org/gentoo-dev/msg_f052911449b1db2271984746dfe730dd.xml) > However, with the advancements of the gtk-doc system, there _might_ not > be any more benefits in rebuilding the documentation, so I've had the > intention to check that out and perhaps propose removing the doc USE > flag completely and never regenerate it if it's true that it has no > point. [...] > I would propose that we (the GNOME team) investigates the benefits (or > lack thereof these days) of the regeneration in the first part of > November, and if we don't, you get to remind us and we take care of it [...] > So, what was the outcome of such investigation?
I just want select a specific documentation... should some ebuild mask /usr/share/gtk-doc/ folder if doc flag is disabled?
*** Bug 290864 has been marked as a duplicate of this bug. ***
(In reply to comment #9) > I just want select a specific documentation... should some ebuild mask > /usr/share/gtk-doc/ folder if doc flag is disabled? I think it's possible to use bashrc for that: put INSTALL_MASK=/usr/share/gtk-doc into /etc/portage/env/${CATEGORY}/${PN}. That said we have incompatibility here as most packages use doc USE flag to install extra documentation, where extra are files not in README, ChangeLog, TODO, AUTHORS and similar... And this is real issue here. @gnome do I understand correctly that gnome does not need to rebuild documentation any more to get correct cross linking any more? What this means for doc USE flag? Will it be removed or what?
That's a good question. We had a tristate issue before, with wishes for 1) Don't install any API docs 2) Don't pull in extra deps just to get cross-linking work, I'm fine with links going off to online or whatever 3) Rebuild docs to get cross-linking work Now with 2) almost out of the equation, I guess it would be possible to satisfy those that want 1) and 3) at the same time without too much complexity. But I think this could be a distro-wide consideration on how to handle API docs better. USE=doc is kind of too broad I think. At any rate, we haven't quite there yet regarding never needing a gtk-doc documentation rebuild, as I don't think gtk-doc-1.13 is stable yet, and not sure everything has new enough gtk-doc.make files in their tarball and whatnot for things to work for everything. Once we are closer to that, we can start pondering about this USE=doc situation deeper. Meanwhile USE=doc still means for us to "rebuild documentation" and not having it means not rebuilding and so not ensuring cross-linking, and to get rid of the API docs installed INSTALL_MASK can be used.
Are there any technical difficulties with doing the following: * Apply tree-wide doc USE flag semantics wrt gtk-doc: USE=doc - installs 'extra' documentation (API docs included) USE=-doc does not install them Whether gtk-docs are rebuilt in the process or not, it's just an implementation detail to me (I also wonder why did you base gtk-doc's 'doc' USE flag semantics on --enable-gtk-doc configure switch). I don't think people are concerned solely about the fact that docs are regenerated when enabled (and that it needs additional dependencies in such case), but mainly about the fact that API docs are installed regardless doc USE flag.
(In reply to comment #13) > Are there any technical difficulties with doing the following: > * Apply tree-wide doc USE flag semantics wrt gtk-doc: > USE=doc - installs 'extra' documentation (API docs included) > USE=-doc does not install them > > Whether gtk-docs are rebuilt in the process or not, it's just an implementation > detail to me (I also wonder why did you base gtk-doc's 'doc' USE flag semantics > on --enable-gtk-doc configure switch). > I don't think people are concerned solely about the fact that docs are > regenerated when enabled (and that it needs additional dependencies in such > case), but mainly about the fact that API docs are installed regardless doc USE > flag. To us whether gtk-docs get rebuilt or not is/was a big concern, not an implementation detail. The rebuilding process can take a huge amount of time depending on the size of the API documented. I think we are talking about 30-90 minutes in case of the largest here
(In reply to comment #13) > Whether gtk-docs are rebuilt in the process or not, it's just an implementation > detail to me (I also wonder why did you base gtk-doc's 'doc' USE flag semantics > on --enable-gtk-doc configure switch). At least in my case: 1. I have a feeling that it takes most of the time of build (over 50%). It might be just feeling but it is, IIRC, not parallelized so such slowdown is likely 2. For sure it is responsible for most of the linking errors in my system. I don't know why but it very often fails due to linking errors.
A couple of issues to remember: * building gtk-doc docs is not a detail, it takes huge amounts of time as already told, notably because of the intervention of scripts for most of the parsing. * getting gtk-doc docs to build requires a load of dependencies which used to break every once in a while (as far as I remember at least) * gettings gtk-doc docs to build reliably is a huge challenge as most upstream don't seem to be able to make them build properly wrt to configure or because having the package already installed interferes with the scanning process, ... all of these issues lead us to decide a couple of weeks/months ago that we should drop doc building and just rely on pre-built docs provided in upstream tarballs with a relink step at installation time. That's what the recent gnome2 eclass changes does, but we need to wait for 1.13 to go stable before continuing our plan.
*** Bug 311401 has been marked as a duplicate of this bug. ***
(In reply to comment #16) > A couple of issues to remember: > * building gtk-doc docs is not a detail, it takes huge amounts of time as > already told, notably because of the intervention of scripts for most of the > parsing. > * getting gtk-doc docs to build requires a load of dependencies which used to > break every once in a while (as far as I remember at least) > * gettings gtk-doc docs to build reliably is a huge challenge as most upstream > don't seem to be able to make them build properly wrt to configure or because > having the package already installed interferes with the scanning process, ... > > all of these issues lead us to decide a couple of weeks/months ago that we > should drop doc building and just rely on pre-built docs provided in upstream > tarballs with a relink step at installation time. That's what the recent gnome2 > eclass changes does, but we need to wait for 1.13 to go stable before > continuing our plan. What is the status of this today? What steps are still pending? Thanks for the info :-)
ping? what's the status?
After quite a few discussion we came to a decision that USE=doc is to be removed altogether of ebuilds only providing this to rebuild gtk-docs and make gtk-doc installation non-conditional. This policy is currently written down here: https://wiki.gentoo.org/wiki/Gnome_Team_Policies Before eventually moving to the project page. I am closing this bug as fixed now since we decided on a clear road and it lifts the ambiguity reported here. Thanks for reporting.
