Excerpts from justin's message of Tue Mar 29 16:24:57 +0200 2011:
> the descriptions of USE flags should explain what the USE is good for.
> In my opinion some thing like
>
> Enables foo intergration
> or
> Enables support for foo
>
> if it isn't totally clear what "foo" is, sucks!! There are many, many
> description which do not tell me as a user without googling what I
> could enable or not. That doesn't make gentoo very user friendly!
>
> So please enhance you descriptions!!

I 100% agree with you! This is something what is always pissing me off
when reading equery uses foo to find out how to set flags.

I'm actually describing even global USE flags in my package's
metadata.xml if their purpose might not be clear and I'd like to expect
that from others. It is not a problem to write one sentence for each
flag while you already know what flag does.

Maybe it should even become our policy and not just recommendation?
--
Amadeusz Żołnowski

PGP key fpr: C700 CEDE 0C18 212E 49DA 4653 F013 4531 E1DB FAB5

On Tue, 29 Mar 2011 16:24:57 +0200
justin <jlec@gentoo.org> wrote:

> if it isn't totally clear what "foo" is, sucks!!

You could start by pointing out some good examples of bad descriptions.

> So please enhance you descriptions!!

And when you do, also remove all exclamation marks. Not all Gentoo
users are used to reading German. ;-)


jer

On Ter, 2011-03-29 at 17:08 +0200, Amadeusz Żołnowski wrote:
> Excerpts from justin's message of Tue Mar 29 16:24:57 +0200 2011:
> > the descriptions of USE flags should explain what the USE is good for.
> > In my opinion some thing like
> >
> > Enables foo intergration
> > or
> > Enables support for foo
> >
> > if it isn't totally clear what "foo" is, sucks!! There are many, many
> > description which do not tell me as a user without googling what I
> > could enable or not. That doesn't make gentoo very user friendly!
> >
> > So please enhance you descriptions!!
>
> I 100% agree with you! This is something what is always pissing me off
> when reading equery uses foo to find out how to set flags.
>
> I'm actually describing even global USE flags in my package's
> metadata.xml if their purpose might not be clear and I'd like to expect
> that from others. It is not a problem to write one sentence for each
> flag while you already know what flag does.
>
> Maybe it should even become our policy and not just recommendation?

Why do we have to turn everything into policies? This case would be
easily solved by making a list of use flags that we find poorly
described, then improving the description of each.
- Angelo

Excerpts from Angelo Arrifano's message of Tue Mar 29 17:14:48 +0200 2011:
> On Ter, 2011-03-29 at 17:08 +0200, Amadeusz Żołnowski wrote:
> > I'm actually describing even global USE flags in my package's
> > metadata.xml if their purpose might not be clear and I'd like to
> > expect that from others. It is not a problem to write one sentence
> > for each flag while you already know what flag does.
> >
> > Maybe it should even become our policy and not just recommendation?
>
> Why do we have to turn everything into policies? This case would be
> easily solved by making a list of use flags that we find poorly
> described, then improving the description of each.

It would be hard to find good descriptions. The problem is that even if
flag has similar meaning in few packages, it usually adds a bit
different functionality and that difference matters. User would like to
know what he/she benefits or looses with enabling/disabling the flag.
It's not just a matter of one click, it at least minutes of compilation.
I think it's a task to package maintainers to review if current
descriptions explain what flags in their packages bring to user.
--
Amadeusz Żołnowski

PGP key fpr: C700 CEDE 0C18 212E 49DA 4653 F013 4531 E1DB FAB5

On 2011-03-29 17:10, Jeroen Roovers wrote:
> You could start by pointing out some good examples of bad
> descriptions.

A few regular expressions might help with that:

/w+) - (Enable|Add) support for 1$/
/w+) - (Enable|Add) 1( support)?$/

For example:

app-admin/puppet:shadow - Enable shadow support
app-editors/tea:hacking - Enable hacking support
app-emulation/q4wine:icoutils - Enable icoutils support
app-misc/roadnavpenstreetmap - Enable openstreetmap support
app-misc/roadnav:scripting - Enable scripting support
app-office/abiword-plugins:thesaurus - Enable thesaurus support
app-office/abiword:thesaurus - Enable thesaurus support
app-pda/barry:boost - Enable boost support
....

On 03/29/2011 08:00 PM, Matt Turner wrote:

On Tue, Mar 29, 2011 at 2:24 PM, justin<jlec@gentoo.org> wrote:

Hi,

the descriptions of USE flags should explain what the USE is good for.
In my opinion some thing like

Enables foo intergration
or
Enables support for foo

if it isn't totally clear what "foo" is, sucks!! There are many, many
description which do not tell me as a user without googling what I could
enable or not. That doesn't make gentoo very user friendly!

So please enhance you descriptions!!


Thanks justin


One USE flag I remember in particular bothering me was
gnome-extra/gnome-games' guile USE flag.

The global description says "guile - Adds support for the guile Scheme
interpreter" but this flag is actually determines whether a number of
games are installed by this package.


The most extreme one I remember is the "gtk" flag of GCC:

"Adds support for x11-libs/gtk+ (The GIMP Toolkit)"

Hmm, OK. So without that flag, GCC won't be able to build gtk? Or gimp?
Or any software using gtk?

Le mardi 29 mars 2011 à 16:02 +0000, Andy Spencer a écrit :
>
> app-office/abiword-plugins:thesaurus - Enable thesaurus support
> app-office/abiword:thesaurus - Enable thesaurus support

can't help you if you don't know what a thesaurus is, really
--
Gilles Dartiguelongue <eva@gentoo.org>
Gentoo

On Tue, Mar 29, 2011 at 2:24 PM, justin <jlec@gentoo.org> wrote:
> Hi,
>
> the descriptions of USE flags should explain what the USE is good for.
> In my opinion some thing like
>
> Enables foo intergration
> or
> Enables support for foo
>
> if it isn't totally clear what "foo" is, sucks!! There are many, many
> description which do not tell me as a user without googling what I could
> enable or not. That doesn't make gentoo very user friendly!
>
> So please enhance you descriptions!!
>
>
> Thanks justin

One USE flag I remember in particular bothering me was
gnome-extra/gnome-games' guile USE flag.

The global description says "guile - Adds support for the guile Scheme
interpreter" but this flag is actually determines whether a number of
games are installed by this package.

There are lots of cases like this that need a local use flag that says
what each flag actually does for the package.

Matt

On Tue, Mar 29, 2011 at 10:30 PM, Matt Turner <mattst88@gentoo.org> wrote:
> One USE flag I remember in particular bothering me was
> gnome-extra/gnome-games' guile USE flag.
>
> The global description says "guile - Adds support for the guile Scheme
> interpreter" but this flag is actually determines whether a number of
> games are installed by this package.
>

Actually, it only controls the installation of aisleriot (solitaire,
freecell, etc). The USE-flag was changed from "guile" to "aisleriot" a
while back, but the changes haven't made it to the tree yet because
newer gnome-games are quite unusable. 2.28 (the current stable) is
almost two years old.


--
~Nirbheek Chauhan

Gentoo GNOME+Mozilla Team

On 29/03/11 18:02, Andy Spencer wrote:
> On 2011-03-29 17:10, Jeroen Roovers wrote:
>> You could start by pointing out some good examples of bad
>> descriptions.
>
> A few regular expressions might help with that:
>
> /w+) - (Enable|Add) support for 1$/
> /w+) - (Enable|Add) 1( support)?$/
>
> For example:
>
> app-admin/puppet:shadow - Enable shadow support
> app-editors/tea:hacking - Enable hacking support
> app-emulation/q4wine:icoutils - Enable icoutils support
> app-misc/roadnavpenstreetmap - Enable openstreetmap support
> app-misc/roadnav:scripting - Enable scripting support
> app-office/abiword-plugins:thesaurus - Enable thesaurus support
> app-office/abiword:thesaurus - Enable thesaurus support
> app-pda/barry:boost - Enable boost support
> ....

These are really not the examples I meant, but I will post some as soon
I stumble on another one.