[gentoo-dev] Please enhance your USE descriptions!

[gentoo-dev] Please enhance your USE descriptions!

[justin]

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

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


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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Amadeusz Żołnowski]

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

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

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Angelo Arrifano]

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Amadeusz Żołnowski]

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

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

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Jeroen Roovers]

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Andy Spencer]

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

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/roadnav:openstreetmap - 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
  ....

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Gilles Dartiguelongue]

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[justin]

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

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/roadnav:openstreetmap - 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.


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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Matt Turner]

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

[gentoo-dev] Re: Please enhance your USE descriptions!

[Nikos Chantziaras]

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?

Re: [gentoo-dev] Please enhance your USE descriptions!

[Nirbheek Chauhan]

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[justin]

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

This is what I mean by good description

+	<flag name="mp3">Enable support for mp3 decoding over
<pkg>media-sound/mpg123</pkg> instead of relying on ffmpeg support.</flag>

instead of the default

mp3 - Add support for reading mp3 files

Everybody understands what mp3 means, but we truely need something else
here.

justin


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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Fabian Groffen]

On 31-03-2011 09:23:16 +0200, justin wrote:
> This is what I mean by good description
> 
> +	<flag name="mp3">Enable support for mp3 decoding over
> <pkg>media-sound/mpg123</pkg> instead of relying on ffmpeg support.</flag>
> 
> instead of the default
> 
> mp3 - Add support for reading mp3 files
> 
> Everybody understands what mp3 means, but we truely need something else
> here.

Are these two descriptions for the same package?  Both messages say
something different to me.  This is not an improvement perse, but just a
correction, because one of the two is (or both are) clearly wrong.

I find the default clear enough.  It seems the mp3 USE-flag is
overloaded with multiple functions, this is likely the cause of the
problem here.



-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Please enhance your USE descriptions!

[Tomáš Chvátal]

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

Dne 31.3.2011 09:33, Fabian Groffen napsal(a):
> On 31-03-2011 09:23:16 +0200, justin wrote:
>> This is what I mean by good description
>>
>> +	<flag name="mp3">Enable support for mp3 decoding over
>> <pkg>media-sound/mpg123</pkg> instead of relying on ffmpeg support.</flag>
>>
>> instead of the default
>>
>> mp3 - Add support for reading mp3 files
>>
>> Everybody understands what mp3 means, but we truely need something else
>> here.
> 
> Are these two descriptions for the same package?  Both messages say
> something different to me.  This is not an improvement perse, but just a
> correction, because one of the two is (or both are) clearly wrong.
> 
> I find the default clear enough.  It seems the mp3 USE-flag is
> overloaded with multiple functions, this is likely the cause of the
> problem here.
> 
> 
> 
The mp3 useflag is correct. It just can use mpg123 which is actualy
better implementation and if you compile mplayer with -mp3 then it looks
to libavcodec for the mp3 support (which is supposed to be worse than
the mpg123).
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2UMBYACgkQHB6c3gNBRYfsPwCgqAfhVNNfGyvwOfDh1MNqc67Q
TLgAn3xvG3Zi/PbZZRLy/WVpuDZTs+uD
=OeN9
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Please enhance your USE descriptions!

[Fabian Groffen]

On 31-03-2011 09:41:10 +0200, Tomáš Chvátal wrote:
> Dne 31.3.2011 09:33, Fabian Groffen napsal(a):
> > On 31-03-2011 09:23:16 +0200, justin wrote:
> >> instead of the default
> >>
> >> mp3 - Add support for reading mp3 files
> > 
> > I find the default clear enough.  It seems the mp3 USE-flag is
> > overloaded with multiple functions, this is likely the cause of the
> > problem here.
> > 
> The mp3 useflag is correct. It just can use mpg123 which is actualy
> better implementation and if you compile mplayer with -mp3 then it looks
> to libavcodec for the mp3 support (which is supposed to be worse than
> the mpg123).

use.desc gives the default USE-description, which says it enables
support for reading mp3 files.  Hence, (based on what you say) the
useflag is incorrect for mplayer, because it can *always* read
mp3-files.

mplayer should not use mp3 USE-flag, because -mp3 to still have a
mp3-reading capable player feels quite counter-intuitive.  It happens to
be that mp3 USE-flag is hooked up to the encode USE-flag -- this is
where it no longer has anything to do with the description from
use.desc.


-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Please enhance your USE descriptions!

[Tomáš Chvátal]

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

Dne 31.3.2011 09:51, Fabian Groffen napsal(a):
> On 31-03-2011 09:41:10 +0200, Tomáš Chvátal wrote:
>> Dne 31.3.2011 09:33, Fabian Groffen napsal(a):
>>> On 31-03-2011 09:23:16 +0200, justin wrote:
>>>> instead of the default
>>>>
>>>> mp3 - Add support for reading mp3 files
>>>
>>> I find the default clear enough.  It seems the mp3 USE-flag is
>>> overloaded with multiple functions, this is likely the cause of the
>>> problem here.
>>>
>> The mp3 useflag is correct. It just can use mpg123 which is actualy
>> better implementation and if you compile mplayer with -mp3 then it looks
>> to libavcodec for the mp3 support (which is supposed to be worse than
>> the mpg123).
> 
> use.desc gives the default USE-description, which says it enables
> support for reading mp3 files.  Hence, (based on what you say) the
> useflag is incorrect for mplayer, because it can *always* read
> mp3-files.
> 
> mplayer should not use mp3 USE-flag, because -mp3 to still have a
> mp3-reading capable player feels quite counter-intuitive.  It happens to
> be that mp3 USE-flag is hooked up to the encode USE-flag -- this is
> where it no longer has anything to do with the description from
> use.desc.
> 
> 
Well technically yep, but for lets say the ffmpeg the mp3 useflag means
"Enable mp3 encoding support." :)

If user sets -mp3 it still can play mp3 tracks but in really worse
quality so it is just nice convinience that ffmpeg always allows playing
those files.

Since i was that kind and disabled internal libmp3 that was first in
order of what would be used simply with -mp3 you will get mplayer
playing mp3 tracks but it is not desirable for you to do so.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2UNx0ACgkQHB6c3gNBRYeKiQCgyoeAnZiTpvOz5cCuSQ32jU/W
Cf0AoJdnIgdu9c/99Qy1i3gLkDIv77cB
=99Me
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Please enhance your USE descriptions!

[Jesús J. Guerrero Botella]

2011/3/31 Tomáš Chvátal <scarabeus@gentoo.org>:
> Well technically yep, but for lets say the ffmpeg the mp3 useflag means
> "Enable mp3 encoding support." :)
>
> If user sets -mp3 it still can play mp3 tracks but in really worse
> quality so it is just nice convinience that ffmpeg always allows playing
> those files.
>
> Since i was that kind and disabled internal libmp3 that was first in
> order of what would be used simply with -mp3 you will get mplayer
> playing mp3 tracks but it is not desirable for you to do so.

However, if I wanted someone else deciding what's "desirable" for me I
wouldn't be using Gentoo, and I wouldn't care about USE flags at all.

The only important thing here is that the label on top of the big red
button doesn't match the purpose of the big red button. The final user
doesn't really care if the USE is global or not, and s/he certainly
doesn't care as much about the USE flag name as s/he can care about
the USE flag purpose.

On the other side, I remind everyone that there's bugs.gentoo.org
which is where everyone should be reporting USE flag bugs instead of
wasting the time here. Just like I do when I feel something is not
right. Things usually get fixed.The last one that got my attention was
the "symlink" flag for mplayer2, I reported it yesterday, now the fix
is in the tree.



-- 
Jesús Guerrero Botella

Re: [gentoo-dev] Please enhance your USE descriptions!

[justin]

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

On 31/03/11 09:33, Fabian Groffen wrote:
> On 31-03-2011 09:23:16 +0200, justin wrote:
>> This is what I mean by good description
>>
>> +	<flag name="mp3">Enable support for mp3 decoding over
>> <pkg>media-sound/mpg123</pkg> instead of relying on ffmpeg support.</flag>
>>
>> instead of the default
>>
>> mp3 - Add support for reading mp3 files
>>
>> Everybody understands what mp3 means, but we truely need something else
>> here.
> 
> Are these two descriptions for the same package?  Both messages say
> something different to me.  This is not an improvement perse, but just a
> correction, because one of the two is (or both are) clearly wrong.
> 
> I find the default clear enough.  It seems the mp3 USE-flag is
> overloaded with multiple functions, this is likely the cause of the
> problem here.
> 
> 
> 

First is a package specific, second is the default.

And no, asuming the USE is introduced correctly here, it makes a
difference, whether we take the global meaning -> reading mp3 files at
all; or changing the way it is done for this package. Because here it
means, you could not disable mp3 support, but rather choose on which way
it should happen.




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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Fabian Groffen]

On 31-03-2011 09:44:37 +0200, justin wrote:
> First is a package specific, second is the default.
> 
> And no, asuming the USE is introduced correctly here, it makes a
> difference, whether we take the global meaning -> reading mp3 files at
> all; or changing the way it is done for this package. Because here it
> means, you could not disable mp3 support, but rather choose on which way
> it should happen.

If a flag is in use.desc (global), then I should be able to put it in my
USE= in my /etc/make.conf.  That also means that the flag should only be
used to do exactly as it says in use.desc, and nothing else.

The package in question here should really use a different USE-flag,
because it is overloading the original (intended?) meaning of the mp3
USE-flag, leading to possibly unexpected results for the end-user.

There is nothing unclear on the descriptions here, the same flag is just
used for two different things, which is wrong if the flag is global.


-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Please enhance your USE descriptions!

[justin]

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

On 31/03/11 09:57, Fabian Groffen wrote:
> On 31-03-2011 09:44:37 +0200, justin wrote:
>> First is a package specific, second is the default.
>>
>> And no, asuming the USE is introduced correctly here, it makes a
>> difference, whether we take the global meaning -> reading mp3 files at
>> all; or changing the way it is done for this package. Because here it
>> means, you could not disable mp3 support, but rather choose on which way
>> it should happen.
> 
> If a flag is in use.desc (global), then I should be able to put it in my
> USE= in my /etc/make.conf.  That also means that the flag should only be
> used to do exactly as it says in use.desc, and nothing else.
> 
> The package in question here should really use a different USE-flag,
> because it is overloading the original (intended?) meaning of the mp3
> USE-flag, leading to possibly unexpected results for the end-user.
> 
> There is nothing unclear on the descriptions here, the same flag is just
> used for two different things, which is wrong if the flag is global.
> 
> 

Lets stop this discussion, because this doesn't has to do with the topic.
All I wanted to do, is illustrating the difference between a missleading
or not understandable USE description, to something, where I directly
get a clue,  what happens if I set it.


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

Re: [gentoo-dev] Please enhance your USE descriptions!

[James Cloos]

>>>>> "j" == justin  <jlec@gentoo.org> writes:

j> In my opinion some thing like

j> Enables foo intergration
j> or
j> Enables support for foo

j> if it isn't totally clear what "foo" is

Even preferring $C/$PN where $PN is currently used would help,
since it makes it clear that the foo is a package.

-JimC
-- 
James Cloos <cloos@jhcloos.com>         OpenPGP: 1024D/ED7DAEA6

Re: [gentoo-dev] Please enhance your USE descriptions!

[Amadeusz Żołnowski]

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

Excerpts from James Cloos's message of Wed Mar 30 18:13:21 +0200 2011:
> j> Enables foo intergration
> j> or
> j> Enables support for foo
> 
> j> if it isn't totally clear what "foo" is
> 
> Even preferring $C/$PN where $PN is currently used would help,
> since it makes it clear that the foo is a package.

The main problem is that user might not know what kind of “foo” support
it is. For example I have “pango” USE flag in sys-boot/plymouth. What
would explain to you something like: “Enables support for
x11-libs/pango”? And how you would compare it with “Adds support for
printing text on splash screen and text prompts, e.g. for password”?
-- 
Amadeusz Żołnowski

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

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Olivier Crête]

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

On Wed, 2011-03-30 at 21:56 +0200, Amadeusz Żołnowski wrote:
> The main problem is that user might not know what kind of “foo” support
> it is. For example I have “pango” USE flag in sys-boot/plymouth. What
> would explain to you something like: “Enables support for
> x11-libs/pango”? And how you would compare it with “Adds support for
> printing text on splash screen and text prompts, e.g. for password”?

I'm sorry, but that's a terrible example.. In this case, it shouldn't be
a use flag at all. We shoudl avoid having use flag where the description
is "Adds support for not being completely broken"

-- 
Olivier Crête
tester@gentoo.org
Gentoo Developer

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Amadeusz Żołnowski]

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

Excerpts from Olivier Crête's message of Wed Mar 30 22:14:30 +0200 2011:
> On Wed, 2011-03-30 at 21:56 +0200, Amadeusz Żołnowski wrote:
> > The main problem is that user might not know what kind of “foo” support
> > it is. For example I have “pango” USE flag in sys-boot/plymouth. What
> > would explain to you something like: “Enables support for
> > x11-libs/pango”? And how you would compare it with “Adds support for
> > printing text on splash screen and text prompts, e.g. for password”?
> 
> I'm sorry, but that's a terrible example.. In this case, it shouldn't be
> a use flag at all. We shoudl avoid having use flag where the description
> is "Adds support for not being completely broken"

Please… We're not actually discussing about what should be flagged or
not, but about descriptions, where I think I have made the point more or
less.

Justin has pointed problem which is worth our attention. It is not just
me being pissed off when reading „Enable support for foo”, there are
many users complaining about that.
-- 
Amadeusz Żołnowski

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

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Dale]

Amadeusz Żołnowski wrote:
> Justin has pointed problem which is worth our attention. It is not just
> me being pissed off when reading „Enable support for foo”, there are
> many users complaining about that.
>    

+1  Some descriptions may as well not have one at all.  May as well 
Google the flag and the package and see what, if anything, it returns.

Dale

:-)  :-)

Re: [gentoo-dev] Please enhance your USE descriptions!

[Aaron W. Swenson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 03/30/2011 05:41 PM, Dale wrote:
> Amadeusz Żołnowski wrote:
>> Justin has pointed problem which is worth our attention. It is not just
>> me being pissed off when reading „Enable support for foo”, there are
>> many users complaining about that.
>>    
> 
> +1  Some descriptions may as well not have one at all.  May as well
> Google the flag and the package and see what, if anything, it returns.
> 
> Dale
> 
> :-)  :-)
> 
More often than not it just returns the Gentoo USE flag description.
Either from g.o itself, or g-p.com which duplicates the same description.

Every now and then you get real lucky and there's a post on f.g.o that
comes close to telling you what it does.

- - Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iF4EAREIAAYFAk2Tse8ACgkQCOhwUhu5AEmxiwD/YVcKJYI82bdlnqcfdlQ5YeJF
G2536ZJ/d5sdkPUTUHMA/RPQpNXpP4NZxuBJL0wU3rlpot7YGRoT6jD7hVAOAgL0
=mk5z
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Please enhance your USE descriptions!

[Dale]

Aaron W. Swenson wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> On 03/30/2011 05:41 PM, Dale wrote:
>    
>> Amadeusz Żołnowski wrote:
>>      
>>> Justin has pointed problem which is worth our attention. It is not just
>>> me being pissed off when reading „Enable support for foo”, there are
>>> many users complaining about that.
>>>
>>>        
>> +1  Some descriptions may as well not have one at all.  May as well
>> Google the flag and the package and see what, if anything, it returns.
>>
>> Dale
>>
>> :-)  :-)
>>
>>      
> More often than not it just returns the Gentoo USE flag description.
> Either from g.o itself, or g-p.com which duplicates the same description.
>
> Every now and then you get real lucky and there's a post on f.g.o that
> comes close to telling you what it does.
>
> - - Aaron
>    

That was why I said "if anything".  Usually, I get just what you are 
describing which gives about zero help.

That said, with the limits the description has, I'm not sure how to 
improve it.  It doesn't have much room to expand.

Dale

:-)  :-)

Re: [gentoo-dev] Please enhance your USE descriptions!

[Eray Aslan]

On Wed, Mar 30, 2011 at 04:41:25PM -0500, Dale wrote:
> +1  Some descriptions may as well not have one at all.  May as well 
> Google the flag and the package and see what, if anything, it returns.

I would say working as intended.  If you do not know what a package
does, chances are you don't need to enable it.  And if you do want
to tinker, USE flags gives you enough of a hint to start googling.

Having said that, we should at least have gramatically correct
English in descriptions.  One might also lean towards more verbosity
in end-user oriented packages (versus server/backend/toolchain
packages).  In any case, 10-15 words should be more than enough to
explain what a USE flag does.

-- 
Eray Aslan
Developer, Gentoo Linux       eras <at> gentoo.org

Re: [gentoo-dev] Please enhance your USE descriptions!

[Dale]

Eray Aslan wrote:
> On Wed, Mar 30, 2011 at 04:41:25PM -0500, Dale wrote:
>    
>> +1  Some descriptions may as well not have one at all.  May as well
>> Google the flag and the package and see what, if anything, it returns.
>>      
> I would say working as intended.  If you do not know what a package
> does, chances are you don't need to enable it.  And if you do want
> to tinker, USE flags gives you enough of a hint to start googling.
>
> Having said that, we should at least have gramatically correct
> English in descriptions.  One might also lean towards more verbosity
> in end-user oriented packages (versus server/backend/toolchain
> packages).  In any case, 10-15 words should be more than enough to
> explain what a USE flag does.
>
>    

As was posted by another person, google usually points right back to the 
Gentoo docs which does not help.  For me, most of the time, the 
descriptions don't help a bit, not even to tinker.  So, given that, 
maybe working as intended but still not very helpful.  Having USE foo to 
say it enables foo does not help much if you don't know what foo is.  
There are a lot of them that says that and it really goes without saying 
that it does that.  If you enable a USE flag, of course it enables the 
flag.  Question is, what the heck is the flag?  What does it do?

Maybe we need a USE flag for smoke.  See if someone tinkers with it and 
blows up their rig.  lol

In all seriousness, this has been discussed before and it doesn't get 
any better.  I'm not sure how to fix it either.  The space for the 
description is limited.

Dale

:-)  :-)

Re: [gentoo-dev] Please enhance your USE descriptions!

[Alec Warner]

On Thu, Mar 31, 2011 at 5:59 AM, Dale <rdalek1967@gmail.com> wrote:
> Eray Aslan wrote:
>>
>> On Wed, Mar 30, 2011 at 04:41:25PM -0500, Dale wrote:
>>
>>>
>>> +1  Some descriptions may as well not have one at all.  May as well
>>> Google the flag and the package and see what, if anything, it returns.
>>>
>>
>> I would say working as intended.  If you do not know what a package
>> does, chances are you don't need to enable it.  And if you do want
>> to tinker, USE flags gives you enough of a hint to start googling.
>>
>> Having said that, we should at least have gramatically correct
>> English in descriptions.  One might also lean towards more verbosity
>> in end-user oriented packages (versus server/backend/toolchain
>> packages).  In any case, 10-15 words should be more than enough to
>> explain what a USE flag does.
>>
>>
>
> As was posted by another person, google usually points right back to the
> Gentoo docs which does not help.  For me, most of the time, the descriptions
> don't help a bit, not even to tinker.  So, given that, maybe working as
> intended but still not very helpful.  Having USE foo to say it enables foo
> does not help much if you don't know what foo is.  There are a lot of them
> that says that and it really goes without saying that it does that.  If you
> enable a USE flag, of course it enables the flag.  Question is, what the
> heck is the flag?  What does it do?
>
> Maybe we need a USE flag for smoke.  See if someone tinkers with it and
> blows up their rig.  lol
>
> In all seriousness, this has been discussed before and it doesn't get any
> better.  I'm not sure how to fix it either.  The space for the description
> is limited.

Read the ebuild?

>
> Dale
>
> :-)  :-)
>
>

Re: [gentoo-dev] Please enhance your USE descriptions!

[Amadeusz Żołnowski]

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

Excerpts from Alec Warner's message of Thu Mar 31 08:23:45 +0200 2011:
> On Thu, Mar 31, 2011 at 5:59 AM, Dale <rdalek1967@gmail.com> wrote:
> > Eray Aslan wrote:
> > In all seriousness, this has been discussed before and it doesn't
> > get any better.  I'm not sure how to fix it either.  The space for
> > the description is limited.

What is the limit? Anyway we can change it, cannot we? And you can
always write shortly something better than “Enable support for foo”.



> On Thu, Mar 31, 2011 at 5:59 AM, Dale <rdalek1967@gmail.com> wrote:
> Read the ebuild?

Read-the-ebuild? And maybe unpack the archive, check configure's help,
read the README, INSTALL and so, and analyze source code to eventually
find out what the flag does? This that what user is supposed to do for
every package?
-- 
Amadeusz Żołnowski

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

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

Re: [gentoo-dev] Please enhance your USE descriptions!

[Dale]

Amadeusz Żołnowski wrote:
> Excerpts from Alec Warner's message of Thu Mar 31 08:23:45 +0200 2011:
>    
>> On Thu, Mar 31, 2011 at 5:59 AM, Dale<rdalek1967@gmail.com>  wrote:
>>      
>>> Eray Aslan wrote:
>>> In all seriousness, this has been discussed before and it doesn't
>>> get any better.  I'm not sure how to fix it either.  The space for
>>> the description is limited.
>>>        
> What is the limit? Anyway we can change it, cannot we? And you can
> always write shortly something better than “Enable support for foo”.
>
>
>    

I don't recall the exact amount but it is sort of small.  After all, if 
there was no limit, some would write a book about the flag.  ;-)

>    
>> On Thu, Mar 31, 2011 at 5:59 AM, Dale<rdalek1967@gmail.com>  wrote:
>> Read the ebuild?
>>      
> Read-the-ebuild? And maybe unpack the archive, check configure's help,
> read the README, INSTALL and so, and analyze source code to eventually
> find out what the flag does? This that what user is supposed to do for
> every package?
>    

If I am expected to read every single thing installed on here, I would 
never get to use the puter for anything else.  I have almost 1,000 
packages on here.  Most of which I really don't need to know the inner 
working of as a user.  USE flags could come in handy tho.  I always 
check them before a upgrade/install.

I was just reading through the USE file, it is a lot better than it used 
to be.  Someone has been doing some work in there.  There are still some 
that I am clueless about but a lot of them are better.  I like these:

directfb - Adds support for DirectFB layer (library for FB devices)
latex - Adds support for LaTeX (typesetting package)

Those two are pretty good to be so short.

Dale

:-)  :-)

Re: [gentoo-dev] Please enhance your USE descriptions!

[Jesús J. Guerrero Botella]

2011/3/31 Eray Aslan <eras@gentoo.org>:
> On Wed, Mar 30, 2011 at 04:41:25PM -0500, Dale wrote:
>> +1  Some descriptions may as well not have one at all.  May as well
>> Google the flag and the package and see what, if anything, it returns.
>
> I would say working as intended.  If you do not know what a package
> does, chances are you don't need to enable it.  And if you do want
> to tinker, USE flags gives you enough of a hint to start googling.

This has nothing to do with what you want to imply here. It's not
about the tech skill of the user reading the definition. It's about
the definitions being generic and vague enough so they can fit eight
thousand packages that doesn't relate in any way, right?

To say that the kde use flag gives "support for kde" says next to
nothing to me on some packages. When I look into the ebuild and/or
into the sources I can see all it does is to copy a .desktop file
somewhere, or to enable the kde file dialog, or to create a window
deco or a plasma snippet, or a phonon backend, or a color scheme.
That's what I wanted to know and there's no way I can know it by
looking at the USE description.

> Having said that, we should at least have gramatically correct
> English in descriptions.  One might also lean towards more verbosity
> in end-user oriented packages (versus server/backend/toolchain
> packages).  In any case, 10-15 words should be more than enough to
> explain what a USE flag does.

Mostly. But try cleaning the ffmpeg/libav-mplayer mess to decide which
codec to use and you will find that a clear explanation (so you can
decide) can't fit into that space.

I don't have a problem reading ebuilds, though having to dive into the
sources of a big package is another story, but I can understand users
that find this an unpractical "solution". After all, if the USE
descriptions doesn't tell a thing we should just remove them because
they are taking space in our portage tree to provide zero info. So,
"kde" flag purpose is to "enable support for KDE", oh,
really?[/sarcasm]

-- 
Jesús Guerrero Botella