[gentoo-dev] USE flag documentation

[gentoo-dev] USE flag documentation

[Mark Loeser]

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

This is a very very rough draft/question about how we should move
forward with USE flag documentation and specification.  The entire idea
of a single USE flag having different meanings will need to be revisted
later.  I just want to get an idea of how we can document these
different meanings.  Please read my ideas here:

http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html

Let me know if you like any of those ideas, or if they all suck (and if
they do, you better tell me why).  I'm not sure which is the best way
forward, which is why I want everyone to contribute towards the best
solution moving forward.  I really don't want to be stuck with something
that is going to end up being a pain a year down the road.

Thanks,

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

Re: [gentoo-dev] USE flag documentation

[Alec Warner]

On 12/30/07, Mark Loeser <halcy0n@gentoo.org> wrote:
> This is a very very rough draft/question about how we should move
> forward with USE flag documentation and specification.  The entire idea
> of a single USE flag having different meanings will need to be revisted
> later.  I just want to get an idea of how we can document these
> different meanings.  Please read my ideas here:
>
> http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html
>
> Let me know if you like any of those ideas, or if they all suck (and if
> they do, you better tell me why).  I'm not sure which is the best way
> forward, which is why I want everyone to contribute towards the best
> solution moving forward.  I really don't want to be stuck with something
> that is going to end up being a pain a year down the road.
>
> Thanks,
>

One of the GLEP's primary goals is to provide a global use flag
definition and over-ride
it with a local definition.  How does putting all flags in use.desc
and over-riding local flags in
use.local.desc not accomplish this?

How does the glep intend to handle USE_EXPAND?
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Denis Dupeyron]

I like the overall idea. I will comment the first proposed alternative
as this is the one that makes the most sense in my opinion.

> Having one global use.xml where the default definitions are, and then using metadata.xml for each package to override the USE flag definition.

With 's/default definitions/global USE flag definitions/' and
's/override the USE flag definition/define the local USE flags/' I
would be even happier. Global USE flags should be defined in a central
place and never be overridden. Local flags should be defined locally
i.e. in the package subdirectory.

I'd even go as far as adding that metadata.xml could include some
clarifications/specifics/notes/warnings/whatever about a global USE
flag for a given package, but that should not be a redefinition of the
global USE flag. This would be appended by third party tools to
complement the definition of the global USE flag in the context of
that particular package.

> Problems with this approach include...
> * Easy to duplicate USE flags since we don't have a central repository for them.

I'm not following you here. We'd have a central use.xml, so what do
you mean ? And it's OK for local flags to be conflicting or duplicated
since they're local.

> Lots of small files to go and parse to get the full picture of the tree.

This can be cached.

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

Re: [gentoo-dev] USE flag documentation

[Doug Klima]

Marius Mauch wrote:
> On Sun, 30 Dec 2007 19:54:04 -0500
> Mark Loeser <halcy0n@gentoo.org> wrote:
> 
>> Let me know if you like any of those ideas, or if they all suck (and if
>> they do, you better tell me why).  I'm not sure which is the best way
>> forward, which is why I want everyone to contribute towards the best
>> solution moving forward.  I really don't want to be stuck with something
>> that is going to end up being a pain a year down the road.
> 
> What benefit does use.xml have over use.desc?
> 
> My opinion is that we should use use.desc for a complete list of use
> flags, including a generic description, allow a more verbose
> description in metadata.xml and get rid of the stupid separation of
> "local" and "global" flags. No need to change the format of use.desc
> though.

I completely agree with this. This allows each individual package to 
provide more insight to what a USE flag does.

> The only benefit use.local.desc gives us is a fast way to list packages
> using some flags, but that's unreliable at best. If needed such a list
> could be autogenerated.
> 
> Marius


-- 
Doug Klima <cardoe@gentoo.org>
http://dev.gentoo.org/~cardoe/
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Denis Dupeyron]

On Dec 31, 2007 3:30 PM, Marius Mauch <genone@gentoo.org> wrote:
> What benefit does use.xml have over use.desc?
[...]
> No need to change the format of use.desc

Anything that would enable us to document with more than a few words,
which is what we're practically limited to with the current format of
use.desc, would help. The currently available documentation on USE
flags is clearly insufficient, maybe not for you and me and other
devs, but for the majority of our users. Note that this is not the
same as optionally adding more specific documentation on a global flag
in the metadata.xml of a package.

> and get rid of the stupid separation of "local" and "global" flags

Good idea. How do you plan to cope with the (currently) local USE flag
conflicts though ?

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

Re: [gentoo-dev] USE flag documentation

[Mark Loeser]

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

Alec Warner <antarus@gentoo.org> said:
> One of the GLEP's primary goals is to provide a global use flag
> definition and over-ride
> it with a local definition.  How does putting all flags in use.desc
> and over-riding local flags in
> use.local.desc not accomplish this?

It does, and maybe that's what we should use instead?  The reason for
the email is to figure out if what we have now is good enough, or if we
should switch to something else.

> How does the glep intend to handle USE_EXPAND?

It doesn't say anything about them right now, but since you brought it
up...any ideas? :)

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

Re: [gentoo-dev] USE flag documentation

[Mark Loeser]

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

Doug Klima <cardoe@gentoo.org> said:
> Marius Mauch wrote:
>> What benefit does use.xml have over use.desc?
>> My opinion is that we should use use.desc for a complete list of use
>> flags, including a generic description, allow a more verbose
>> description in metadata.xml and get rid of the stupid separation of
>> "local" and "global" flags. No need to change the format of use.desc
>> though.
>
> I completely agree with this. This allows each individual package to 
> provide more insight to what a USE flag does.

This sounds sane to me as well.  As I said, I'm just throwing ideas out
there to see what sticks :)

>> The only benefit use.local.desc gives us is a fast way to list packages
>> using some flags, but that's unreliable at best. If needed such a list
>> could be autogenerated.

Completely agree.

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

Re: [gentoo-dev] USE flag documentation

[Marius Mauch]

On Mon, 31 Dec 2007 18:55:10 +0100
"Denis Dupeyron" <calchan@gentoo.org> wrote:

> On Dec 31, 2007 3:30 PM, Marius Mauch <genone@gentoo.org> wrote:
> > What benefit does use.xml have over use.desc?
> [...]
> > No need to change the format of use.desc
> 
> Anything that would enable us to document with more than a few words,
> which is what we're practically limited to with the current format of
> use.desc, would help. The currently available documentation on USE
> flags is clearly insufficient, maybe not for you and me and other
> devs, but for the majority of our users. Note that this is not the
> same as optionally adding more specific documentation on a global flag
> in the metadata.xml of a package.

Most of the time when I see complaints about the description of USE
flags (I'm fully aware of those) the issue isn't the format, just that
noone else has come up with a better description. And technically
use.desc isn't limited to "a few words", unless you want to add
multiple paragraphs with formatting, just the (current) presentation
would get a bit ugly with longer descriptions. Of course the format
could be changed if needed, but that needs a more specific description
about the requirements.

> > and get rid of the stupid separation of "local" and "global" flags
> 
> Good idea. How do you plan to cope with the (currently) local USE flag
> conflicts though ?

You mean different descriptions? Just use a placeholder in use.desc
(like some global flags already have) and move the actual description
in metadata.xml if there isn't any common base.

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

[gentoo-dev] Re: USE flag documentation

[Duncan]

Marius Mauch <genone@gentoo.org> posted
20080101060928.2a500186.genone@gentoo.org, excerpted below, on  Tue, 01
Jan 2008 06:09:28 +0100:

> Most of the time when I see complaints about the description of USE
> flags (I'm fully aware of those) the issue isn't the format, just that
> noone else has come up with a better description.

There are, I believe, two complaints, but one you don't see often as many 
don't think it's currently possible with a global USE flag (and possible 
but seldom done with local flags).

The first complaint is poor descriptions in general.  "foo - Adds foo 
support" just doesn't cut it.  (See USE=glw, for instance.  USE=gif's 
"Adds GIF image support" is at least somewhat better, saying GIF is an 
image format, at least.  I haven't a clue what libGlw does, except that 
it says requires mesa, which I know is 3D, so I suppose it's related to 
that, but what if someone doesn't know what mesa is?)  This seems to be 
the one you are addressing.

The second complaint, a frustration I often find myself experiencing, is 
that particularly with global flags, it's difficult to see exactly what 
they do in a particular package without actually seeing what the ebuild 
does.  Does it add the dependency and link against it?  Does it install 
example code and/or documentation for it?  Does it install bindings for 
it?  Is it build (static) against the included version vs using the 
system copy?  Does it not change what's supported at all, only the 
library/codec implementation used to handle it (the case with mp3/lame/
whatever sometimes)?  Etc.

It'd sure be nice to be able to run an euse -i flag and get the details 
of what flag actually does for various packages, or euse -i flag package, 
and get the info for just that package.  It'd be /real/ nice if emerge 
had a -vv or -vvv mode, that spit out what all the use flags actually did 
for those packages, at the detail level of the questions above.  If 
whatever proposal makes that easier, I say go for it. =8^)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Doug Klima]

Mark Loeser wrote:
> Alec Warner <antarus@gentoo.org> said:
>   
>> One of the GLEP's primary goals is to provide a global use flag
>> definition and over-ride
>> it with a local definition.  How does putting all flags in use.desc
>> and over-riding local flags in
>> use.local.desc not accomplish this?
>>     
>
> It does, and maybe that's what we should use instead?  The reason for
> the email is to figure out if what we have now is good enough, or if we
> should switch to something else.
>
>   

You're the one forcing people to remove overriding USE flags from
use.local.desc when that's something that people have been doing for
ages. The current Portage tools support that method.
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] USE flag documentation

[Mark Loeser]

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

Doug Klima <cardoe@gentoo.org> said:
> You're the one forcing people to remove overriding USE flags from
> use.local.desc when that's something that people have been doing for
> ages. The current Portage tools support that method.

Because this behaviour is not documented anywhere, and if you check, the
only ones I've removed so far are ones that are word for word
duplicates.  I'm also not sure if using the existing use.desc and
use.local.desc is the best way to move forward.

I have these different suggestions to see which one people like the best
and to see how I can improve upon them.

Thanks,

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

Re: [gentoo-dev] USE flag documentation

[Piotr Jaroszyński]

On Wednesday 02 of January 2008 16:58:33 Mark Loeser wrote:
> Doug Klima <cardoe@gentoo.org> said:
> > You're the one forcing people to remove overriding USE flags from
> > use.local.desc when that's something that people have been doing for
> > ages. The current Portage tools support that method.
>
> Because this behaviour is not documented anywhere

It is documented in the PMS draft and imho it makes perfect sense (at least 
with current solution):

"Flags must be listed once for each package to which they apply, or if a flag 
is listed in both use.desc and use.local.desc, it must be listed once for 
each package for which its meaning differs from that described in use.desc."

-- 
Best Regards,
Piotr Jaroszyński
--
gentoo-dev@gentoo.org mailing list

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Mark Loeser wrote:
> Here is a newer revision of the GLEP.  I still have multiple methods of
> solving this problem (mostly because I want and *need* input from people
> as to what they would prefer).  Please tell me what you would want to
> use so I can come up with a more precise specification.  What exactly do
> we need this system to do that we can't do now?  Is overriding the USE
> flag with use.local.desc sufficient and we just need to document the
> current solution properly?
> 
> Please...let me know how you feel about this.
> 
> http://dev.gentoo.org/~halcy0n/gleps/glep-0054.html
> 
> Thanks,

What do people think of this?

a) Keep use.desc as it is:  a list of common flags and a short general 
description of their meaning.

b) Keep use.local.desc as it is: a list of per-package flags that are specific 
to one to a few ebuilds (i think 5 is the number though i think 10 is more 
appropriate, but that's not relevant to this discussion).  Again, each has a 
short description.

c) Allow flags from use.desc to also exist in use.local.desc.  In the case that 
a flag for a package exists in both, the use.local.desc description overrides 
the use.desc one.  This allows a more specific per-package description of global 
flags.

d) Allow long descriptions in a package's metadata.xml, as some have begun to do 
already, for cases where more info is needed.  For example I'd like to explain 
exactly what the bindist flag on freetype does and what legal implications 
disabling it can have.

The reason I suggest we do it this way is it's very close to what we're already 
doing now.  The only thing we'd need to do is decide it's okay to do (c) and 
adapt our various utils to use the use.local.desc description when both exist. 
I actually planned on proposing something like this about a year ago but never 
got around to it.  But at the time I did some poking and found that several of 
our utils already did the right thing while the others needed minor adjustments 
(I think I had a one-line patch for equery).  We also needn't worry about 
breaking 3rd party tools.  The worst that would happen is they'd display the 
use.desc description, which is what they do now.

On the other hand, if there are any far-reaching changes we need made to the USE 
flag system - any features we wish we had or misfeatures we wish we didn't - now 
would be a good time to address them.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

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

Re: [gentoo-dev] Re: USE flag documentation

[Vlastimil Babka]

Ryan Hill wrote:
> What do people think of this?
> 
> a) Keep use.desc as it is:  a list of common flags and a short general 
> description of their meaning.

Good.

> b) Keep use.local.desc as it is: a list of per-package flags that are 
> specific to one to a few ebuilds (i think 5 is the number though i think 
> 10 is more appropriate, but that's not relevant to this discussion).  
> Again, each has a short description.
> 
> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
> case that a flag for a package exists in both, the use.local.desc 
> description overrides the use.desc one.  This allows a more specific 
> per-package description of global flags.

Good.

> d) Allow long descriptions in a package's metadata.xml, as some have 
> begun to do already, for cases where more info is needed.  For example 
> I'd like to explain exactly what the bindist flag on freetype does and 
> what legal implications disabling it can have.

Right. Also why not also add short descriptions there, and deprecate 
use.local.desc when tools are converted? Placing package-local info to 
global files (when not needed to distinguish profiles as with 
package.use.mask etc) is icky.
Note that the metadata.xml should be able to record per-version 
differences somehow.

> On the other hand, if there are any far-reaching changes we need made to 
> the USE flag system - any features we wish we had or misfeatures we wish 
> we didn't - now would be a good time to address them.

I wish for use deps :P
Well, addressing conflicts and implications between flags at ebuild/PM 
level would be also nice, but really shouldn't affect the way 
documentation is handled, IMHO.

VB
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] Re: USE flag documentation

[Mark Loeser]

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

Ryan Hill <dirtyepic@gentoo.org> said:
> a) Keep use.desc as it is:  a list of common flags and a short general 
> description of their meaning.

Sounds good.

> b) Keep use.local.desc as it is: a list of per-package flags that are 
> specific to one to a few ebuilds (i think 5 is the number though i think 10 
> is more appropriate, but that's not relevant to this discussion).  Again, 
> each has a short description.

Also fine.

> c) Allow flags from use.desc to also exist in use.local.desc.  In the case 
> that a flag for a package exists in both, the use.local.desc description 
> overrides the use.desc one.  This allows a more specific per-package 
> description of global flags.

Still doing alright :)

> d) Allow long descriptions in a package's metadata.xml, as some have begun 
> to do already, for cases where more info is needed.  For example I'd like 
> to explain exactly what the bindist flag on freetype does and what legal 
> implications disabling it can have.

Why can't this be done in use.local.desc?

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Mark Loeser wrote:
> Ryan Hill <dirtyepic@gentoo.org> said:
>> a) Keep use.desc as it is:  a list of common flags and a short general 
>> description of their meaning.
> 
> Sounds good.
> 
>> b) Keep use.local.desc as it is: a list of per-package flags that are 
>> specific to one to a few ebuilds (i think 5 is the number though i think 10 
>> is more appropriate, but that's not relevant to this discussion).  Again, 
>> each has a short description.
> 
> Also fine.
> 
>> c) Allow flags from use.desc to also exist in use.local.desc.  In the case 
>> that a flag for a package exists in both, the use.local.desc description 
>> overrides the use.desc one.  This allows a more specific per-package 
>> description of global flags.
> 
> Still doing alright :)
> 
>> d) Allow long descriptions in a package's metadata.xml, as some have begun 
>> to do already, for cases where more info is needed.  For example I'd like 
>> to explain exactly what the bindist flag on freetype does and what legal 
>> implications disabling it can have.
> 
> Why can't this be done in use.local.desc?

My expectation is that `grep "flag" use.local.desc` will give me a list of 
packages using that flag (or having it in the description), one per line. 
Putting paragraphs in there doesn't seem right.

-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

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

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

Vlastimil Babka wrote:
> Ryan Hill wrote:
>> What do people think of this?
>>
>> a) Keep use.desc as it is:  a list of common flags and a short general 
>> description of their meaning.
> 
> Good.
> 
>> b) Keep use.local.desc as it is: a list of per-package flags that are 
>> specific to one to a few ebuilds (i think 5 is the number though i 
>> think 10 is more appropriate, but that's not relevant to this 
>> discussion).  Again, each has a short description.
>>
>> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
>> case that a flag for a package exists in both, the use.local.desc 
>> description overrides the use.desc one.  This allows a more specific 
>> per-package description of global flags.
> 
> Good.
> 
>> d) Allow long descriptions in a package's metadata.xml, as some have 
>> begun to do already, for cases where more info is needed.  For example 
>> I'd like to explain exactly what the bindist flag on freetype does and 
>> what legal implications disabling it can have.
> 
> Right. Also why not also add short descriptions there, and deprecate 
> use.local.desc when tools are converted? Placing package-local info to 
> global files (when not needed to distinguish profiles as with 
> package.use.mask etc) is icky.
> Note that the metadata.xml should be able to record per-version 
> differences somehow.

Then instead of grepping a file I would need to read XML.  Also icky.  Utils 
would help, but then utils would need to implement an XML parser.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662

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

Re: [gentoo-dev] Re: USE flag documentation

[Chris Gianelloni]

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

On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> My expectation is that `grep "flag" use.local.desc` will give me a
> list of packages using that flag (or having it in the description),
> one per line. Putting paragraphs in there doesn't seem right.

A single long line still fills this "requirement" for us.  However, it
does bring up the point.  Why even have use.local.desc (or
metadata.xml's <use> tag) at all?  Is there really a need for a *global*
list of flags that are ebuild-specific?  (I don't care or have much
opinion, either way, I'm merely presenting some topic for discussion on
this.)

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Games Developer

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

Re: [gentoo-dev] Re: USE flag documentation

[Alec Warner]

On 1/15/08, Chris Gianelloni <wolf31o2@gentoo.org> wrote:
> On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> > My expectation is that `grep "flag" use.local.desc` will give me a
> > list of packages using that flag (or having it in the description),
> > one per line. Putting paragraphs in there doesn't seem right.
>
> A single long line still fills this "requirement" for us.  However, it
> does bring up the point.  Why even have use.local.desc (or
> metadata.xml's <use> tag) at all?  Is there really a need for a *global*
> list of flags that are ebuild-specific?  (I don't care or have much
> opinion, either way, I'm merely presenting some topic for discussion on
> this.)

The global use.* files are convenient because it means we don't need
to generate or push a cache for the data (like for metadata).  If it
was per package or per-ebuild we would need to generate a cache to
answer queries like 'what does the "foo" flag do'.

>
> --
> Chris Gianelloni
> Release Engineering Strategic Lead
> Games Developer
>
>
-- 
gentoo-dev@lists.gentoo.org mailing list

Re: [gentoo-dev] Re: USE flag documentation

[Mark Loeser]

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

Ryan Hill <dirtyepic@gentoo.org> said:
> Mark Loeser wrote:
>> Ryan Hill <dirtyepic@gentoo.org> said:
>>> c) Allow flags from use.desc to also exist in use.local.desc.  In the 
>>> case that a flag for a package exists in both, the use.local.desc 
>>> description overrides the use.desc one.  This allows a more specific 
>>> per-package description of global flags.
>> Still doing alright :)
>>> d) Allow long descriptions in a package's metadata.xml, as some have 
>>> begun to do already, for cases where more info is needed.  For example 
>>> I'd like to explain exactly what the bindist flag on freetype does and 
>>> what legal implications disabling it can have.
>> Why can't this be done in use.local.desc?
>
> My expectation is that `grep "flag" use.local.desc` will give me a list of 
> packages using that flag (or having it in the description), one per line. 
> Putting paragraphs in there doesn't seem right.

One could argue that you can't do that currently for DEPEND strings and
such, so that seems like a possibly weak argument to me.  Just because
you can do something right now doesn't mean it was meant to be that way,
or shouldn't be changed to make things better :)

Either way, I would prefer (and I'm sure others will as well since it
will cut down on confusion) if we pick either use.local.desc or to move
them into metadata.xml.  Having it possibly be in both places just seems
silly.

-- 
Mark Loeser
email         -   halcy0n AT gentoo DOT org
email         -   mark AT halcy0n DOT com
web           -   http://www.halcy0n.com

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

Re: [gentoo-dev] Re: USE flag documentation

[Donnie Berkholz]

On 18:45 Tue 15 Jan     , Alec Warner wrote:
> On 1/15/08, Chris Gianelloni <wolf31o2@gentoo.org> wrote:
> > On Tue, 2008-01-15 at 17:00 -0600, Ryan Hill wrote:
> > > My expectation is that `grep "flag" use.local.desc` will give me a
> > > list of packages using that flag (or having it in the description),
> > > one per line. Putting paragraphs in there doesn't seem right.
> >
> > A single long line still fills this "requirement" for us.  However, it
> > does bring up the point.  Why even have use.local.desc (or
> > metadata.xml's <use> tag) at all?  Is there really a need for a *global*
> > list of flags that are ebuild-specific?  (I don't care or have much
> > opinion, either way, I'm merely presenting some topic for discussion on
> > this.)
> 
> The global use.* files are convenient because it means we don't need
> to generate or push a cache for the data (like for metadata).  If it
> was per package or per-ebuild we would need to generate a cache to
> answer queries like 'what does the "foo" flag do'.

Since Chris only mentioned use.local.desc, I'm assuming he only meant 
local flags rather than use.desc also. In that case, asking what the 
"foo" local flag does doesn't make sense, because it does something 
different depending on the package you're curious about. Centralizing 
what feels like inherently local data seems odd to me. USE flag editors 
would still need to generate a complete list, though, so this would make 
more work for them.

Chris, I'm not entirely clear what you meant by your suggestion of also 
dropping metadata.xml <use>; where would we describe local flags?

Thanks,
Donnie
-- 
gentoo-dev@lists.gentoo.org mailing list

[gentoo-dev] Re: USE flag documentation

[Ryan Hill]

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

Mark Loeser wrote:
> Ryan Hill <dirtyepic@gentoo.org> said:

>> My expectation is that `grep "flag" use.local.desc` will give me a list of 
>> packages using that flag (or having it in the description), one per line. 
>> Putting paragraphs in there doesn't seem right.

> One could argue that you can't do that currently for DEPEND strings and
> such, so that seems like a possibly weak argument to me.  Just because
> you can do something right now doesn't mean it was meant to be that way,
> or shouldn't be changed to make things better :)
> 
> Either way, I would prefer (and I'm sure others will as well since it
> will cut down on confusion) if we pick either use.local.desc or to move
> them into metadata.xml.  Having it possibly be in both places just seems
> silly.

If we have to choose between the two, then metadata.xml gets my vote (yeah i'm
contradicting myself here ;)).  I think the benefits of being able to write long
flag descriptions outweigh the benefits of having them all in one place.

I'd like it if we had a util that displayed the descriptions from metadata
before (if) we switch over though.


-- 
fonts,                                            by design, by neglect
gcc-porting,                              for a fact or just for effect
wxwindows @ gentoo     EFFD 380E 047A 4B51 D2BD C64F 8AA8 8346 F9A4 0662


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