[gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Petteri Räty]

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

For example the gnome people use the doc use flag to control whether
gtk-doc gets rebuild using cross references:

16:51 <@leio> as far as I'm concerned the doc USE flag means rebuilding
documentation to get cross-referencing in docs working
16:51 <@leio> also the lack of doc USE flag does not mean to not install
documentation
16:52 <@leio> it means to not take a long time to build documentation,
and we are not doing it if doc USE flag is not present

This leads to having tons of gtk-doc installed:
betelgeuse@pena ~ $ du -sh /usr/share/gtk-doc/html/
51M     /usr/share/gtk-doc/html/

In for example Java we use it to control Javadoc installation. Javadoc
generation rarely takes much time and needs no extra dependencies but
having Javadocs for everything would consume a lot of space.

My opinion is to make it clear that the doc use flag always controls
whether or not to install documentation and make it clear in the
devmanual. For what gnome does, they can then add for example a gtk-doc
use flag to control the building of the cross references and have the
doc use flag control the installation of the bundled documentation.

betelgeuse@pena ~ $ euse -i doc
global use flags (searching: doc)
************************************************************
[-    ] doc - Adds extra documentation (API, Javadoc, etc)

INSTALL_MASK is of course a solution to not installing gtk-doc at all
but it doesn't give me the ability to install it only for individual
packages.

What do others think?

Regards,
Petteri


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

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Ciaran McCreesh]

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

On Sat, 23 Jun 2007 17:11:16 +0300
Petteri Räty <betelgeuse@gentoo.org> wrote:
> My opinion is to make it clear that the doc use flag always controls
> whether or not to install documentation and make it clear in the
> devmanual.

The doc use flag is used where there is a reason to make documentation
optional rather than mandatory. Examples of such reasons include
increased dependencies (e.g. Doxygen, which pulls in a fair bit),
increased build time (e.g. Doxygen, which can be frickin' slow) or
substantially increased disk usage. If there's no substantial cost to
documentation, it should always be installed.

-- 
Ciaran McCreesh


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Petteri Räty]

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

Ciaran McCreesh kirjoitti:
> On Sat, 23 Jun 2007 17:11:16 +0300
> Petteri Räty <betelgeuse@gentoo.org> wrote:
>> My opinion is to make it clear that the doc use flag always controls
>> whether or not to install documentation and make it clear in the
>> devmanual.
> 
> The doc use flag is used where there is a reason to make documentation
> optional rather than mandatory. Examples of such reasons include
> increased dependencies (e.g. Doxygen, which pulls in a fair bit),
> increased build time (e.g. Doxygen, which can be frickin' slow) or
> substantially increased disk usage. If there's no substantial cost to
> documentation, it should always be installed.
> 

Yep but we should for example document what constitues increased disk
usage. How about "several megabytes or tens of files"?

Regards,
Petteri


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

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Ciaran McCreesh]

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

On Sat, 23 Jun 2007 17:45:02 +0300
Petteri Räty <betelgeuse@gentoo.org> wrote:
> > The doc use flag is used where there is a reason to make
> > documentation optional rather than mandatory. Examples of such
> > reasons include increased dependencies (e.g. Doxygen, which pulls
> > in a fair bit), increased build time (e.g. Doxygen, which can be
> > frickin' slow) or substantially increased disk usage. If there's no
> > substantial cost to documentation, it should always be installed.
> > 
> 
> Yep but we should for example document what constitues increased disk
> usage. How about "several megabytes or tens of files"?

It's a package dependent quantity, and should be left up to individual
maintainers. Vim's documentation, for example, is a lot of files and a
lot of disk space, but it isn't shipped via USE="doc" because it's
considered by upstream to be a vital part of the package.

-- 
Ciaran McCreesh


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Mart Raudsepp]

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

On L, 2007-06-23 at 15:57 +0100, Ciaran McCreesh wrote:
> On Sat, 23 Jun 2007 17:45:02 +0300
> Petteri Räty <betelgeuse@gentoo.org> wrote:
> > > The doc use flag is used where there is a reason to make
> > > documentation optional rather than mandatory. Examples of such
> > > reasons include increased dependencies (e.g. Doxygen, which pulls
> > > in a fair bit),

Rebuilding of gtk-doc driven documentation means a gtk-doc dep and in
turn a big bunch of xslt and xml and other doc building stuff.

> increased build time (e.g. Doxygen, which can be
> > > frickin' slow)

gtk+ documentation rebuilding can take as much as 30 to 60 minutes with
the doc USE flag for example. The benefit is cross references to glib,
pango and cairo documentation - upstream can not do that as they do not
know where the other docs will be found on disk. Though I should see if
they can not use relative paths somehow..
On the other hand the release tarballs already include a prebuilt
documentation, that is mostly API docs, but also chapters like 'running
gtk+ applications'

> or substantially increased disk usage.

$ du -hs /usr/share/gtk-doc/html/
72M     /usr/share/gtk-doc/html/

$ ls /usr/share/gtk-doc/html/ |wc -l
76

Less than a megabyte per package in average.

gtk+ and pygtk docs are over 10MB and might warrant a reconsideration of
doc installation, but the rest are all less than 3MB, mostly less than a
megabyte and 675KB in average.
I would say there is no reason to not install documentation for other
packages than gtk+ and pygtk.
Even if gtk+ and pygtk docs are always installed it's not very bad.

> If there's no
> > > substantial cost to documentation, it should always be installed

As dang pointed out further on IRC, doc USE flag also takes care of not
depending on a big bunch of extra dependencies.
Additionally the doc USE flag means 'extra' documentation in the sense
of extra value for the docs. It also means substantially longer build
times with the doc USE flag, which seems to be often the practice of
when the doc USE flag is used by a package - substantial time cost.

> > 
> > Yep but we should for example document what constitues increased disk
> > usage. How about "several megabytes or tens of files"?
> 
> It's a package dependent quantity, and should be left up to individual
> maintainers. Vim's documentation, for example, is a lot of files and a
> lot of disk space, but it isn't shipped via USE="doc" because it's
> considered by upstream to be a vital part of the package.


Regarding ungeneralizing the doc USE flag:
For gnome that would probably mean just using apidoc instead of doc
across the board, as it is taken care of by the eclass right now for all
gnome packages, plus gtk-doc docs are almost all for API docs.
If we need to make doc installation optional, it will mean another extra
USE flag for all gnome packages, as I see it as some want to rebuild the
docs, and some do not see the extra value to outweight the much bigger
build times.

What if we made the biggest docs optional but keep all the remaining
gtk-docs installed always, filterable by INSTALL_MASK, as they are
typically less than a megabyte?
Though a gentoo-wide ungeneralizing of doc USE flag doesn't sound bad
indeed.


-- 
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: 189 bytes --]

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Daniel Drake]

Mart Raudsepp wrote:
> gtk+ documentation rebuilding can take as much as 30 to 60 minutes with
> the doc USE flag for example. The benefit is cross references to glib,
> pango and cairo documentation - upstream can not do that as they do not
> know where the other docs will be found on disk. Though I should see if
> they can not use relative paths somehow..

You might consider moving these docs to a separate package aimed at 
people developing using GTK+. gtk+ would then not install these 
documents at all.

We did something similar with kernel docs (see sys-kernel/linux-docs) 
and there have been no complaints so far.

Daniel
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Marius Mauch]

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

On Sat, 23 Jun 2007 17:11:16 +0300
Petteri Räty <betelgeuse@gentoo.org> wrote:

> My opinion is to make it clear that the doc use flag always controls
> whether or not to install documentation and make it clear in the
> devmanual. For what gnome does, they can then add for example a
> gtk-doc use flag to control the building of the cross references and
> have the doc use flag control the installation of the bundled
> documentation.
> 
> betelgeuse@pena ~ $ euse -i doc
> global use flags (searching: doc)
> ************************************************************
> [-    ] doc - Adds extra documentation (API, Javadoc, etc)
> 
> INSTALL_MASK is of course a solution to not installing gtk-doc at all
> but it doesn't give me the ability to install it only for individual
> packages.
> 
> What do others think?

Maybe the flag needs to be renamed/split up to clarify it's meaning,
it's too generic in it's current form (many people enable it blindly and
don't really have any clue what the result is). 
Like using USE=apidoc for API documentation, USE=extradoc for extra
user documentation (controlling PDF generation and stuff like that),
USE=rebuild-docs to replace pregenerated documentation with
updated/regenerated versions (like the gtk-doc issue), and so on (don't
know what other use cases there are for USE=doc currently).

It's a large change, but USE=doc has been a significant problem for
quite a while already (circular deps anyone?)

Marius

-- 
Public Key at http://www.genone.de/info/gpg-key.pub

In the beginning, there was nothing. And God said, 'Let there be
Light.' And there was still nothing, but you could see a bit better.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] RFC: Unifying the behavior of the doc use flag and document it

[Petteri Räty]

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

Marius Mauch kirjoitti:
> On Sat, 23 Jun 2007 17:11:16 +0300
> Petteri Räty <betelgeuse@gentoo.org> wrote:
> 
>> My opinion is to make it clear that the doc use flag always controls
>> whether or not to install documentation and make it clear in the
>> devmanual. For what gnome does, they can then add for example a
>> gtk-doc use flag to control the building of the cross references and
>> have the doc use flag control the installation of the bundled
>> documentation.
>>
>> betelgeuse@pena ~ $ euse -i doc
>> global use flags (searching: doc)
>> ************************************************************
>> [-    ] doc - Adds extra documentation (API, Javadoc, etc)
>>
>> INSTALL_MASK is of course a solution to not installing gtk-doc at all
>> but it doesn't give me the ability to install it only for individual
>> packages.
>>
>> What do others think?
> 
> Maybe the flag needs to be renamed/split up to clarify it's meaning,
> it's too generic in it's current form (many people enable it blindly and
> don't really have any clue what the result is). 
> Like using USE=apidoc for API documentation, USE=extradoc for extra
> user documentation (controlling PDF generation and stuff like that),
> USE=rebuild-docs to replace pregenerated documentation with
> updated/regenerated versions (like the gtk-doc issue), and so on (don't
> know what other use cases there are for USE=doc currently).
> 
> It's a large change, but USE=doc has been a significant problem for
> quite a while already (circular deps anyone?)
> 

That does sound like a good idea.

Regards,
Petteri


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

[gentoo-dev] Re: RFC: Unifying the behavior of the doc use flag and document it

[Steve Long]

Petteri Räty wrote:
>> Maybe the flag needs to be renamed/split up to clarify it's meaning,
>> it's too generic in it's current form (many people enable it blindly and
>> don't really have any clue what the result is).
>> Like using USE=apidoc for API documentation, USE=extradoc for extra
>> user documentation (controlling PDF generation and stuff like that),
>> USE=rebuild-docs to replace pregenerated documentation with
>> updated/regenerated versions (like the gtk-doc issue), and so on (don't
>> know what other use cases there are for USE=doc currently).
>> 
>> It's a large change, but USE=doc has been a significant problem for
>> quite a while already (circular deps anyone?)
>> 
> 
> That does sound like a good idea.
> 
++ I was only thinking of the programmer:user difference, since code docs
tend to pull in a lot of stuff, where as end-user docs are normally
supplied in an easier format (eg not dox ;) rebuild-docs as a one-shot flag
is great.

Would there be a way to control what kind of markup is output (assuming a
package supports it)? For example, to specify that files should be for
text-only or graphical browser (where both would be the default.) XeTeX --
PS -- PDF is another along those lines.


-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: RFC: Unifying the behavior of the doc use flag and document it

[Kent Fredric]

On 6/25/07, Steve Long <slong@rathaus.eclipse.co.uk> wrote:
> Petteri Räty wrote:
> >> Maybe the flag needs to be renamed/split up to clarify it's meaning,
> >> it's too generic in it's current form (many people enable it blindly and
> >> don't really have any clue what the result is).
> >> Like using USE=apidoc for API documentation, USE=extradoc for extra
> >> user documentation (controlling PDF generation and stuff like that),
> >> USE=rebuild-docs to replace pregenerated documentation with
> >> updated/regenerated versions (like the gtk-doc issue), and so on (don't
> >> know what other use cases there are for USE=doc currently).
> >>
> >> It's a large change, but USE=doc has been a significant problem for
> >> quite a while already (circular deps anyone?)
> >>
> >
> > That does sound like a good idea.
> >
> ++ I was only thinking of the programmer:user difference, since code docs
> tend to pull in a lot of stuff, where as end-user docs are normally
> supplied in an easier format (eg not dox ;) rebuild-docs as a one-shot flag
> is great.
>
> Would there be a way to control what kind of markup is output (assuming a
> package supports it)? For example, to specify that files should be for
> text-only or graphical browser (where both would be the default.) XeTeX --
> PS -- PDF is another along those lines.


I can just feel a USE expansion coming on.

DOC="none pdf txt man ps html info all rebuild" sounds like just a
bunch for starters.

Any votees?


-- 
Kent
ruby -e '[1, 2, 4, 7, 0, 9, 5, 8, 3, 10, 11, 6, 12, 13].each{|x|
print "enNOSPicAMreil kdrtf@gma.com"[(2*x)..(2*x+1)]}'
--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: RFC: Unifying the behavior of the doc use flag and document it

[Ciaran McCreesh]

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

On Mon, 25 Jun 2007 01:42:15 +1200
"Kent Fredric" <kentfredric@gmail.com> wrote:
> I can just feel a USE expansion coming on.
> 
> DOC="none pdf txt man ps html info all rebuild" sounds like just a
> bunch for starters.
> 
> Any votees?

No. It doesn't generalise well across packages.

-- 
Ciaran McCreesh


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

[gentoo-dev] Re: Re: RFC: Unifying the behavior of the doc use flag and document it

[Steve Long]

Kent Fredric wrote:
>> ++ I was only thinking of the programmer:user difference, since code docs
>> tend to pull in a lot of stuff, where as end-user docs are normally
>> supplied in an easier format (eg not dox ;) rebuild-docs as a one-shot
>> flag is great.
>>
>> Would there be a way to control what kind of markup is output (assuming a
>> package supports it)? For example, to specify that files should be for
>> text-only or graphical browser (where both would be the default.) XeTeX
>> -- PS -- PDF is another along those lines.
> 
> I can just feel a USE expansion coming on.
> 
> DOC="none pdf txt man ps html info all rebuild" sounds like just a
> bunch for starters.
> 
> Any votees?
> 
Not me, I'm afraid, unless this is the only way to do it.. I agree that they
should only apply to single packages, not across the tree. Although, if I'm
honest, I don't know what that breaks.


-- 
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: Re: RFC: Unifying the behavior of the doc use flag and document it

[Steve Long]

Steve Long wrote:
> Kent Fredric wrote:
>>> ++ I was only thinking of the programmer:user difference, since code
>>> docs tend to pull in a lot of stuff, where as end-user docs are normally
>>> supplied in an easier format (eg not dox ;) rebuild-docs as a one-shot
>>> flag is great.
>>>
>>> Would there be a way to control what kind of markup is output (assuming
>>> a package supports it)? For example, to specify that files should be for
>>> text-only or graphical browser (where both would be the default.) XeTeX
>>> -- PS -- PDF is another along those lines.
>> 
>> I can just feel a USE expansion coming on.
>> 
>> DOC="none pdf txt man ps html info all rebuild" sounds like just a
>> bunch for starters.
>> 
>> Any votees?
>> 
> Not me, I'm afraid, unless this is the only way to do it.. I agree that
> they should only apply to single packages, not across the tree. Although,
> if I'm honest, I don't know what that breaks.
> 
Hmm I've been thinking on this a bit more, and I think it does generalise
well in user terms. After all, if I want documents in text only format for
an installation, it applies to all packages.

What concerned me more was 1) whether it would expand to all by default, as
other expansions do (not so major with profiles perhaps?) and 2) being able
to override if we do want eg html for a package we develop with. But
according to ivanm, you can override with package.use e.g. linguas_en_gb so
long as you know the prefix (ie doc_).

So consider that a positive vote from me :) Though I must stress I want tex
in there ;)

Useful tip btw:
<ivanm> if you have udept emerged, then doing dep -u <package name> will
tell you _all_ the use vars, including the expanded ones


-- 
gentoo-dev@gentoo.org mailing list