[gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 520 bytes --]

Currently the doc use flag on gtk-doc using packages does not control
doc installation but instead whether to rebuild them so that they are
properly cross linked. I think we should be using a separate use flag
from doc for this purpose. Any comments?

15:40 <@Betelgeuse> EvaSDK: Just change the doc use flag to something
else and it won't confuse people
15:56 <@EvaSDK> Betelgeuse: it not like it's been like this forever...
15:56 <@EvaSDK> send a mail to -dev if you want to discuss it

Regards,
Petteri


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Thomas Sachau]

[-- Attachment #1: Type: text/plain, Size: 844 bytes --]

Petteri Räty schrieb:
> Currently the doc use flag on gtk-doc using packages does not control
> doc installation but instead whether to rebuild them so that they are
> properly cross linked. I think we should be using a separate use flag
> from doc for this purpose. Any comments?
> 
> 15:40 <@Betelgeuse> EvaSDK: Just change the doc use flag to something
> else and it won't confuse people
> 15:56 <@EvaSDK> Betelgeuse: it not like it's been like this forever...
> 15:56 <@EvaSDK> send a mail to -dev if you want to discuss it
> 
> Regards,
> Petteri
> 

Why not do both (rebuild and install) with the doc useflag and none of both, if it is not set? Imho
the doc flag is for control of installation for (additional) docs, the way it is used for gtk-doc is
surely confusing.

-- 
Thomas Sachau

Gentoo Linux Developer


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 315 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Rémi Cardona]

Thomas Sachau a écrit :
> Why not do both (rebuild and install) with the doc useflag and none of both, if it is not set? Imho
> the doc flag is for control of installation for (additional) docs, the way it is used for gtk-doc is
> surely confusing.
>

Building gtk-doc documentation pulls in a lot of deps. Installing it 
requires only some disk-space. For a full Gnome system, I only have 96M 
of docs.

As for rebuilding docs, one of the advantage is to correctly crosslink 
docs for tools such as dev-util/devhelp.

If anyone is _that_ short on diskspace, we'll gladly take patches :)

Cheers

Rémi

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Thomas Sachau]

[-- Attachment #1: Type: text/plain, Size: 1510 bytes --]

Rémi Cardona schrieb:
> Thomas Sachau a écrit :
>> Why not do both (rebuild and install) with the doc useflag and none of
>> both, if it is not set? Imho
>> the doc flag is for control of installation for (additional) docs, the
>> way it is used for gtk-doc is
>> surely confusing.
>>
> 
> Building gtk-doc documentation pulls in a lot of deps. Installing it
> requires only some disk-space. For a full Gnome system, I only have 96M
> of docs.
> 
> As for rebuilding docs, one of the advantage is to correctly crosslink
> docs for tools such as dev-util/devhelp.
> 
> If anyone is _that_ short on diskspace, we'll gladly take patches :)
> 
> Cheers
> 
> Rémi
> 
> 

Did i say something about disk space? I say, you are using the doc use flag in a way that is not
expected. The global use flag says, it installs additional documentation. But your doc use flag does
not install anything additional, but instead rebuilds those docs. There is nothing wrong with
rebuilding them on use=doc, but imho you should also only install those docs with use=doc.

The patch could be as simple as adding >use doc || rm -rf "${D}"usr/share/gtk-doc< at the end of
src_install()-function in gnome2.eclass, that should be simple enough to apply without a patch. :)

Btw: e.g. x11-libs/gtk+ has no doc use flag, does not rebuild those docs, but does also install
those docs as reported in bug 239524.

-- 
Thomas Sachau

Gentoo Linux Developer
use doc || rm -rf "${D}usr/share/gtk-doc


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 315 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Gilles Dartiguelongue]

[-- Attachment #1: Type: text/plain, Size: 1251 bytes --]

Le dimanche 05 octobre 2008 à 20:34 +0200, Thomas Sachau a écrit :
> Did i say something about disk space? I say, you are using the doc use flag in a way that is not
> expected. The global use flag says, it installs additional documentation. But your doc use flag does
> not install anything additional, but instead rebuilds those docs. There is nothing wrong with
> rebuilding them on use=doc, but imho you should also only install those docs with use=doc.
> 
> The patch could be as simple as adding >use doc || rm -rf "${D}"usr/share/gtk-doc< at the end of
> src_install()-function in gnome2.eclass, that should be simple enough to apply without a patch. :)

I've not dig that information but it seems to me this is the way it is
because gtk-doc configure switch itself acts like this.

Now if ones digs the archive of this mailing list, I think there was
some talk about renaming the flag for compilation vs. installation only
in order to be more consistent with global use flag meaning but I can't
remember the outcome.

Besides if one really doesn't want to install _any_ gtk-doc there is
still the INSTALL_MASK option (I know it's for l33t users reading mans,
but...).
-- 
Gilles Dartiguelongue <eva@gentoo.org>
Gentoo

[-- Attachment #2: Ceci est une partie de message numériquement signée --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 3076 bytes --]

On P, 2008-10-05 at 20:34 +0200, Thomas Sachau wrote:
> Rémi Cardona schrieb:
> > Thomas Sachau a écrit :
> >> Why not do both (rebuild and install) with the doc useflag and none of
> >> both, if it is not set? Imho
> >> the doc flag is for control of installation for (additional) docs, the
> >> way it is used for gtk-doc is
> >> surely confusing.
> >>
> > 
> > Building gtk-doc documentation pulls in a lot of deps. Installing it
> > requires only some disk-space. For a full Gnome system, I only have 96M
> > of docs.
> > 
> > As for rebuilding docs, one of the advantage is to correctly crosslink
> > docs for tools such as dev-util/devhelp.
> > 
> > If anyone is _that_ short on diskspace, we'll gladly take patches :)
> > 
> > Cheers
> > 
> > Rémi
> > 
> > 
> 
> Did i say something about disk space? I say, you are using the doc use flag in a way that is not
> expected.

The doc USE flag is typically used when it means additional
dependencies, noticeable build time increase or extra downloads. For all
the GNOME packages the former two apply for USE=doc because it requires
a hefty dependency list for doc generation and a long documentation
regeneration time.
The tradition is to always install documentation that is already
available. That is what we do. Those that want extra benefits of waiting
on the doc building to get better doc hyperlinking and such, can do so
with USE=doc, which is expected to take a longer time to build.

> The global use flag says, it installs additional documentation. But your doc use flag does
> not install anything additional, but instead rebuilds those docs. There is nothing wrong with
> rebuilding them on use=doc, but imho you should also only install those docs with use=doc.

Docs are installed always when they do not mean extra downloads, build
time or dependencies. They don't if they are kept in the form they are
in the tarballs already, so we already install them, just like many
other packages do (including all the dodoc's)

> The patch could be as simple as adding >use doc || rm -rf "${D}"usr/share/gtk-doc< at the end of
> src_install()-function in gnome2.eclass, that should be simple enough to apply without a patch. :)

Sorry, I'm not convinced there is anything to patch or change here.

> Btw: e.g. x11-libs/gtk+ has no doc use flag, does not rebuild those docs, but does also install
> those docs as reported in bug 239524.

It does have a doc USE flag, and it controls the same thing it does for
everything else gtk-doc - passing --disable-gtk-doc or --enable-gtk-doc
which acts like described above for regeneration.


Making USE=doc control both installation and regeneration is out of the
question. The benefits of rebuilding are not that big that everyone
would want to do that, especially with recent versions of gtk-doc, but
some do want it. Use INSTALL_MASK if you don't want developer API docs
is the current stance.


-- 
Mart Raudsepp
Gentoo Developer
Mail: leio@gentoo.org
Weblog: http://planet.gentoo.org/developers/leio

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 197 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 1894 bytes --]

Mart Raudsepp kirjoitti:
> On P, 2008-10-05 at 20:34 +0200, Thomas Sachau wrote:
>> Rémi Cardona schrieb:
>>> Thomas Sachau a écrit :
>>>> Why not do both (rebuild and install) with the doc useflag and none of
>>>> both, if it is not set? Imho
>>>> the doc flag is for control of installation for (additional) docs, the
>>>> way it is used for gtk-doc is
>>>> surely confusing.
>>>>
>>> Building gtk-doc documentation pulls in a lot of deps. Installing it
>>> requires only some disk-space. For a full Gnome system, I only have 96M
>>> of docs.
>>>
>>> As for rebuilding docs, one of the advantage is to correctly crosslink
>>> docs for tools such as dev-util/devhelp.
>>>
>>> If anyone is _that_ short on diskspace, we'll gladly take patches :)
>>>
>>> Cheers
>>>
>>> Rémi
>>>
>>>
>> Did i say something about disk space? I say, you are using the doc use flag in a way that is not
>> expected.
> 
> The doc USE flag is typically used when it means additional
> dependencies, noticeable build time increase or extra downloads. For all
> the GNOME packages the former two apply for USE=doc because it requires
> a hefty dependency list for doc generation and a long documentation
> regeneration time.
> The tradition is to always install documentation that is already
> available. That is what we do. Those that want extra benefits of waiting
> on the doc building to get better doc hyperlinking and such, can do so
> with USE=doc, which is expected to take a longer time to build.
> 

With USE="doc" the GNOME packages behave like what you expect but it's
the USE="-doc" case that's in question here. With USE="-doc" you don't
get any use flags installed normally and if it's in the tarball and is
always installed then there is no doc in IUSE either. Global use flags
should behave about the same for both on and off cases.

Regards,
Petteri


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 260 bytes --]

Re: [gentoo-dev] Changing doc use flag on gtk-doc packages to gtk-doc-rebuild or something else

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 1918 bytes --]

On E, 2008-10-06 at 03:46 +0300, Petteri Räty wrote:
> With USE="doc" the GNOME packages behave like what you expect but it's
> the USE="-doc" case that's in question here. With USE="-doc" you don't
> get any use flags installed normally and if it's in the tarball and is
> always installed then there is no doc in IUSE either. Global use flags
> should behave about the same for both on and off cases.

So you propose we would always install the documentation, but have a new
global USE flag (remember, we are talking about over a hundred of
packages here - everything that inherits gnome2.eclass) with a yet to be
determined name to control the re-generation?

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. But checking this has been quite a low priority, and given that
we need to get GNOME-2.24 out there for the users, it remains so during
this month, at least for me.

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
as the hurry with a new major GNOME version, that users are awaiting
(including squashing all bugs needed before stabilization), will be over
then.

Taking the renaming of the USE flag approach as a start would also mean
touching many GNOME packages (build-depends on gtk-doc if eautoreconf is
involved), and I'd rather not risk that at the moment. It would also
heavily disrupts the moving of the new version ebuilds from overlay to
portage tree.


-- 
Mart Raudsepp
Gentoo Developer
Mail: leio@gentoo.org
Weblog: http://planet.gentoo.org/developers/leio

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 197 bytes --]