[gentoo-dev] New global USE flag: examples

[gentoo-dev] New global USE flag: examples

[Matthieu Sozeau]

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

Hi,
	I would like to add this USE flag, which i could use for a lot of ebuilds (I 
actually install provided examples along the documentation sometimes, not 
always, and I suspect others do the same). Thoughts, flames ? (No, you can't 
attack this proposal by saying we already have too much flags :).
-- 
"Knowledge speaks, but wisdom listens."
- Jimi Hendrix

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

Re: [gentoo-dev] New global USE flag: examples

[Norberto Bensa]

Matthieu Sozeau wrote:
> (No, you
> can't attack this proposal by saying we already have too much flags :).

there are too many... oh, never mind.

Seriously, the only thing I got against USE flags is: lack of documentation. 
Gentoo needs more descriptive comments for Uflags. Many times you see 
something like this:

 # emerge -pv package
 [ebuild  N    ] cat/package-0.1 -flag1 -whatever1 +whatever2 23 kB

And when you go to use.local.desc all you see is:

 cat/package:flag1 - enables flag1 compilation/support

It doesn't say what flag1 is good for! So you end up Googleing, etc... 

Best regards,
Norberto



--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] New global USE flag: examples

[Ciaran McCreesh]

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

On Sat, 21 Aug 2004 21:37:50 +0200 Matthieu Sozeau <mattam@gentoo.org>
wrote:
| Hi,
| 	I would like to add this USE flag, which i could use for a lot
| 	of ebuilds (I 
| actually install provided examples along the documentation sometimes,
| not always, and I suspect others do the same). Thoughts, flames ? (No,
| you can't attack this proposal by saying we already have too much
| flags :).-- 

List of ebuilds please?

-- 
Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


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

Re: [gentoo-dev] New global USE flag: examples

[Ciaran McCreesh]

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

On Sat, 21 Aug 2004 16:46:15 -0300 Norberto Bensa
<norberto+gentoo-dev@bensa.ath.cx> wrote:
| And when you go to use.local.desc all you see is:
| 
|  cat/package:flag1 - enables flag1 compilation/support
| 
| It doesn't say what flag1 is good for! So you end up Googleing, etc...

You might want to file bugs for these... Updating use{,.local}.desc
doesn't take particularly long, and a good description can save users a
lot of time.

-- 
Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


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

Re: [gentoo-dev] New global USE flag: examples

[Carsten Lohrke]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Saturday 21 August 2004 21:48, Ciaran McCreesh wrote:
> List of ebuilds please?

Oh, there are a few, but I wonder if this is really necessary. I used always 
the doc use flag.


Carsten
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)

iD8DBQFBJ6mLVwbzmvGLSW8RAlJuAJ9gYQbWh+Yisetccpmng5A+DRcikQCgobIO
ob4n1YEQKdR1NOOuMPQOr5o=
=at3V
-----END PGP SIGNATURE-----

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] New global USE flag: examples

[Matthieu Sozeau]

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

On Saturday 21 August 2004 21:48, Ciaran McCreesh wrote:
> On Sat, 21 Aug 2004 21:37:50 +0200 Matthieu Sozeau <mattam@gentoo.org>
>
> wrote:
> | Hi,
> | 	I would like to add this USE flag, which i could use for a lot
> | 	of ebuilds (I
> | actually install provided examples along the documentation sometimes,
> | not always, and I suspect others do the same). Thoughts, flames ? (No,
> | you can't attack this proposal by saying we already have too much
> | flags :).--
>
> List of ebuilds please?

In dev-ml: equeue, lablgl, lablgtk, res, camlimages, ounit,...The list is 
pretty long and the examples are sometimes big (eg: an IRC client in 
lablgtk).
-- 
BOFH Excuse #294: PCMCIA slave driver 

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

Re: [gentoo-dev] New global USE flag: examples

[Norberto Bensa]

Ciaran McCreesh wrote:
> On Sat, 21 Aug 2004 16:46:15 -0300 Norberto Bensa
>
> <norberto+gentoo-dev@bensa.ath.cx> wrote:
> | And when you go to use.local.desc all you see is:
> |
> |  cat/package:flag1 - enables flag1 compilation/support
> |
> | It doesn't say what flag1 is good for! So you end up Googleing, etc...
>
> You might want to file bugs for these... 

I was just thinking how to make this easy for everyone; I mean, easy for devs, 
users, and bugzilla. I'd not want to fill b.g.o with descriptions for UFlags. 

What about something like the duplicates thread from f.g.o? A bug -and only 
one- at which everyone could contribute descriptions.

Best regards,
Norberto

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] New global USE flag: examples

[Ciaran McCreesh]

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

On Sat, 21 Aug 2004 17:15:09 -0300 Norberto Bensa
<norberto+gentoo-dev@bensa.ath.cx> wrote:
| > | It doesn't say what flag1 is good for! So you end up Googleing,
| > | etc...
| >
| > You might want to file bugs for these... 
| 
| I was just thinking how to make this easy for everyone; I mean, easy
| for devs, users, and bugzilla. I'd not want to fill b.g.o with
| descriptions for UFlags. 
| 
| What about something like the duplicates thread from f.g.o? A bug -and
| only one- at which everyone could contribute descriptions.

That'd be a nightmare. Each maintainer would have to figure out what's
been done already and what still needs to be done, since individual
lines in bugzilla comments can't be marked as 'fixed'.

(Incidentally, this is why we also REALLY REALLY HATE keyword requests
being posted to the forums.)

-- 
Ciaran McCreesh : Gentoo Developer (Sparc, MIPS, Vim, Fluxbox)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


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

Re: [gentoo-dev] New global USE flag: examples

[Stroller]

On Aug 21, 2004, at 9:15 pm, Norberto Bensa wrote:

> Ciaran McCreesh wrote:
>>
>> You might want to file bugs for these...
>
> I was just thinking how to make this easy for everyone; I mean, easy 
> for devs,
> users, and bugzilla. I'd not want to fill b.g.o with descriptions for 
> UFlags.

I have felt the same way in the past, and mentioned USEless 
descriptions on this list in the past.
   http://thread.gmane.org/gmane.linux.gentoo.devel/17486
   http://thread.gmane.org/gmane.linux.gentoo.devel/15741

If Mr McCreesh says to file bugs, then that is what I shall do in the 
future. Thanks!   :D

Stroller


--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] New global USE flag: examples

[Karl Trygve Kalleberg]

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

On Sat, Aug 21, 2004 at 09:37:50PM +0200, Matthieu Sozeau wrote:
> Hi,
> 	I would like to add this USE flag, which i could use for a lot of ebuilds (I 
> actually install provided examples along the documentation sometimes, not 
> always, and I suspect others do the same). Thoughts, flames ? (No, you can't 
> attack this proposal by saying we already have too much flags :).

I second this.

I have a good many packages which come with rather big examples, in addition
to ordinary documentation.

In fact, for some of the Java packages, and example may actually be an entire
(web)application, complete with documentation of its own.

If this gets ratified, I'd also recommend we try to refactor the existing
packages with 'doc' keywords, albeit slowly, since I know many of those
include examples when doc is enabled.

-- Karl T

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

Re: [gentoo-dev] New global USE flag: examples

[Michael Sterrett -Mr. Bones.-]

On Sun, 22 Aug 2004, Karl Trygve Kalleberg wrote:

> I have a good many packages which come with rather big examples, in addition
> to ordinary documentation.
> 
> In fact, for some of the Java packages, and example may actually be an entire
> (web)application, complete with documentation of its own.
> 
> If this gets ratified, I'd also recommend we try to refactor the existing
> packages with 'doc' keywords, albeit slowly, since I know many of those
> include examples when doc is enabled.

The "doc" USE flag isn't for installing basic docs for a package -
those should already be part of a normal merge.  The doc use flag is for
installing "extra" documentaion of any kind.  Making the installation of
examples dependent on the "doc" use flag is perfectly fine.  I don't see
that adding an extra use flag specifically for examples as a good idea.

Michael Sterrett
  -Mr. Bones.-
mr_bones_@gentoo.org

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] New global USE flag: examples

[Karl Trygve Kalleberg]

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

On Sat, Aug 21, 2004 at 08:52:24PM -0400, Michael Sterrett -Mr. Bones.- wrote:

> The "doc" USE flag isn't for installing basic docs for a package -
> those should already be part of a normal merge.  The doc use flag is for
> installing "extra" documentaion of any kind.  Making the installation of
> examples dependent on the "doc" use flag is perfectly fine.  I don't see
> that adding an extra use flag specifically for examples as a good idea.

In java, we have many libraries that are a few hundred kb, that come with
multiple megabytes of generated documentation, that you will only need if
you're a Java developer, and usually not even then.

Also, as javadoc is a memory hog, generating the documentation may be
prohibitive on older machines.

For this reason, we have opted for not installing API documentation by
default.


In addition, some packages come with even bigger examples, that, as I pointed
out, may be full-fledged applications on their own. Even only a small
percentage of Java developers would every want to bother about that, but they
may very well want to have the API docs.

Hence, we have a very real need to separate between docs and examples.


Even though 'examples' may never turn up as a global USE flag, I'm pretty
confident that we'll add it to a good many packages maintained by the Java
herd as a local USE flag in the not-so-distant future.


-- Karl T

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

Re: [gentoo-dev] New global USE flag: examples

[Spider]

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

begin  quote
On Sun, 22 Aug 2004 04:34:38 +0200
Karl Trygve Kalleberg <karltk@gentoo.org> wrote:

> 
> In java, we have many libraries that are a few hundred kb, that come
> with multiple megabytes of generated documentation, that you will only
> need if you're a Java developer, and usually not even then.


> Also, as javadoc is a memory hog, generating the documentation may be
> prohibitive on older machines.

Actually, you just describe the reason we implemented the "doc" useflag.
Its not meant for enduser documentation in that sense, but for more
massive, developer oriented documentation that is autogenerated in some
ways.  okay, its misnamed, I realized that afterwards, too late.

it was basically there to stop packages from pulling in t1, tetex,
openjade, ghostscript and the rest, just to parse some .h headers with a
perl script and generate documentation in multitudes of formats.


So, the documentation / javadoc, are best off covered by the USE="doc"
flag, whereas examples should probably be split up a bit further.
(examplecode !) 

Its fairly important that we don't start to misuse such a flag for
example configurations, which should be considered necessary base level
documentation for users, not "examples" in the sense we are talking
about here.

(for a typical "example" app, freepascal is an example ;)


//Spider




-- 
begin  .signature
Tortured users / Laughing in pain
See Microsoft KB Article Q265230 for more information.
end

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

Re: [gentoo-dev] New global USE flag: examples

[Mike Frysinger]

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

On Saturday 21 August 2004 11:44 pm, Spider wrote:
> Actually, you just describe the reason we implemented the "doc" useflag.
> Its not meant for enduser documentation in that sense, but for more
> massive, developer oriented documentation that is autogenerated in some
> ways.  okay, its misnamed, I realized that afterwards, too late.

agreed ... if a user puts 'doc' into global USE, well that's their fault their 
emerges suddenly take much longer ;)
-mike

[-- Attachment #2: signature --]
[-- Type: application/pgp-signature, Size: 838 bytes --]

Re: [gentoo-dev] New global USE flag: examples

[Matthieu Sozeau]

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

Hi,
	as there are no strong objections (yet) to this proposal, i will add
"examples - Adds examples (code, sample documents... NOT sample 
configurations)" to use.desc tomorrow if no one complains.
-- 
If it happens once, it's a bug.
If it happens twice, it's a feature.
If it happens more than twice, it's a design philosophy.

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

[gentoo-dev] Re: New global USE flag: examples

[Michael Sterrett -Mr. Bones.-]

On Sun, 22 Aug 2004, Matthieu Sozeau wrote:

> 	as there are no strong objections (yet) to this proposal, i will add
> "examples - Adds examples (code, sample documents... NOT sample 
> configurations)" to use.desc tomorrow if no one complains.

I can see I wasn't clear enough before.

I object.  The use of the "doc" use flag should cover the installation of
the example code in question.  There is no need to add yet another global
use flag for this.

Michael Sterrett
  -Mr. Bones.-
mr_bones_@gentoo.org

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: New global USE flag: examples

[Matthieu Sozeau]

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

On Sun, Aug 22, 2004 at 03:12:54PM -0400, Michael Sterrett -Mr. Bones.- wrote:
> On Sun, 22 Aug 2004, Matthieu Sozeau wrote:
> 
> > 	as there are no strong objections (yet) to this proposal, i will add
> > "examples - Adds examples (code, sample documents... NOT sample 
> > configurations)" to use.desc tomorrow if no one complains.
> 
> I can see I wasn't clear enough before.

You didn't follow up on the thread you started which turned out to advocate 
(at least I interpreted it this way) for a distinct 'examples' USE flag, 
perhaps renamed, so I pushed a little :)

> I object.  The use of the "doc" use flag should cover the installation of
> the example code in question.  There is no need to add yet another global
> use flag for this.

What if examples was used like a doc subflag ? The point is that some
people may want docs but not examples (if they know the API well for
example) (and rarely examples but no docs i suspect) and it should be
supported by ebuilds, if possible in a general way. What would you say
if Karl or myself add 'examples' local USE flags for some ebuilds ?

-- Matthieu

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

Re: [gentoo-dev] New global USE flag: examples

[Paul de Vrieze]

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

On Saturday 21 August 2004 21:52, Ciaran McCreesh wrote:
> On Sat, 21 Aug 2004 16:46:15 -0300 Norberto Bensa
>
> <norberto+gentoo-dev@bensa.ath.cx> wrote:
> | And when you go to use.local.desc all you see is:
> |
> |  cat/package:flag1 - enables flag1 compilation/support
> |
> | It doesn't say what flag1 is good for! So you end up Googleing,
> | etc...
>
> You might want to file bugs for these... Updating use{,.local}.desc
> doesn't take particularly long, and a good description can save users a
> lot of time.

The problem is that many "even official global useflags" would sometimes 
require package-level descriptions on their effect. Maybe this should be 
put in the ebuild itself.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

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

Re: [gentoo-dev] New global USE flag: examples

[Paul de Vrieze]

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

On Saturday 21 August 2004 22:28, Ciaran McCreesh wrote:
> On Sat, 21 Aug 2004 17:15:09 -0300 Norberto Bensa
> That'd be a nightmare. Each maintainer would have to figure out what's
> been done already and what still needs to be done, since individual
> lines in bugzilla comments can't be marked as 'fixed'.
>
> (Incidentally, this is why we also REALLY REALLY HATE keyword requests
> being posted to the forums.)

Appart from this being inefficient. There are enough developers that 
hardly or never watch the forums. Let alone monitor it, which is 
impossible (both the quantity and the forum setup don't allow making sure 
that all or nearly all messages are read)

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

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

Re: [gentoo-dev] Re: New global USE flag: examples

[Paul de Vrieze]

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

On Sunday 22 August 2004 21:12, Michael Sterrett -Mr. Bones.- wrote:
> On Sun, 22 Aug 2004, Matthieu Sozeau wrote:
> >  as there are no strong objections (yet) to this proposal, i will add
> > "examples - Adds examples (code, sample documents... NOT sample
> > configurations)" to use.desc tomorrow if no one complains.
>
> I can see I wasn't clear enough before.
>
> I object.  The use of the "doc" use flag should cover the installation
> of the example code in question.  There is no need to add yet another
> global use flag for this.

I disagree with you. Documentation is very different from example 
applications and the like. The java herd is not the only group having 
problems with this. Look for example at the formidable example collection 
provided in qt. In most cases it is not necessary at all to compile them 
all (take quite some time), while developer docs might be interesting.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

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

Re: [gentoo-dev] New global USE flag: examples

[Tuan Van]

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

Paul de Vrieze wrote:

>On Saturday 21 August 2004 21:52, Ciaran McCreesh wrote:
>  
>
>>On Sat, 21 Aug 2004 16:46:15 -0300 Norberto Bensa
>>
>><norberto+gentoo-dev@bensa.ath.cx> wrote:
>>| And when you go to use.local.desc all you see is:
>>|
>>|  cat/package:flag1 - enables flag1 compilation/support
>>|
>>| It doesn't say what flag1 is good for! So you end up Googleing,
>>| etc...
>>
>>You might want to file bugs for these... Updating use{,.local}.desc
>>doesn't take particularly long, and a good description can save users a
>>lot of time.
>>    
>>
>
>The problem is that many "even official global useflags" would sometimes 
>require package-level descriptions on their effect. Maybe this should be 
>put in the ebuild itself.
>
>Paul
>
>  
>
I agree with you. I would like something as `configure --help` for 
example `emerge -useflag foo`, portage parse USE description from the 
ebuild and output something similar to `configure --help`.


-- 
Tuan Van
Gentoo Net-Mail Team
GnuPG key: 6476B2FD
Key server: pgp.mit.edu
Fingerprint: 4CB6 83BD 32D1 BE77 FD14  400B D962 CD73 6476 B2FD


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

Re: [gentoo-dev] Re: New global USE flag: examples

[Mike Frysinger]

On Monday 23 August 2004 08:30 am, Paul de Vrieze wrote:
> I disagree with you. Documentation is very different from example
> applications and the like. The java herd is not the only group having
> problems with this. Look for example at the formidable example collection
> provided in qt. In most cases it is not necessary at all to compile them
> all (take quite some time), while developer docs might be interesting.

doc works fine if you consider the context ...

USE=doc [some programming language] -> i get a lot of programming related 
documentation

USE=doc [some program] -> i get a lot of manuals and extraneous things

looks fine to me ... simply putting USE=doc is a user's problem
-mike

--
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Re: New global USE flag: examples

[Matthieu Sozeau]

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

On Monday 23 August 2004 16:36, Mike Frysinger wrote:
> On Monday 23 August 2004 08:30 am, Paul de Vrieze wrote:
> > I disagree with you. Documentation is very different from example
> > applications and the like. The java herd is not the only group having
> > problems with this. Look for example at the formidable example collection
> > provided in qt. In most cases it is not necessary at all to compile them
> > all (take quite some time), while developer docs might be interesting.
>
> doc works fine if you consider the context ...
>
> USE=doc [some programming language] -> i get a lot of programming related
> documentation
USE="doc examples" [some programming language] -> i get the language ref 
manual and library docs + some example programs if provided.

> USE=doc [some program] -> i get a lot of manuals and extraneous things
USE="doc examples" [some program] -> i get a lot of manuals and some sample 
documents (could be used in Dia for example).

USE=doc [some library] -> i get the API docs
USE="doc examples" -> ^^^ + example code/apps

You seem to see it too fine-grained, but there are people who want API docs 
but not example code (I am a living example). USE flags are about 
flexibility, aren't they ? Micheal says there is no need, that's true, but 
some people wish this USE flag existed so they could have more control on 
what's installed.
-- 
"We have art to save ourselves from the truth." 
- Friedrich Nietzsche

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