[gentoo-dev] Re: USE flag documentation
Mark Loeser wrote: > Ryan Hill <[EMAIL PROTECTED]> 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 signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Re: USE flag documentation
On 18:45 Tue 15 Jan , Alec Warner wrote: > On 1/15/08, Chris Gianelloni <[EMAIL PROTECTED]> 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 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 ; where would we describe local flags? Thanks, Donnie -- gentoo-dev@lists.gentoo.org mailing list
Re: [gentoo-dev] Re: USE flag documentation
Ryan Hill <[EMAIL PROTECTED]> said: > Mark Loeser wrote: >> Ryan Hill <[EMAIL PROTECTED]> 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 pgpKNKGoZLuMg.pgp Description: PGP signature
Re: [gentoo-dev] Re: USE flag documentation
On 1/15/08, Chris Gianelloni <[EMAIL PROTECTED]> 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 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
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 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 signature.asc Description: This is a digitally signed message part
[gentoo-dev] Re: USE flag documentation
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
[gentoo-dev] Re: USE flag documentation
Mark Loeser wrote: Ryan Hill <[EMAIL PROTECTED]> 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
Re: [gentoo-dev] Re: USE flag documentation
Ryan Hill <[EMAIL PROTECTED]> 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 pgpty7jvR7m5f.pgp Description: PGP signature
Re: [gentoo-dev] Re: USE flag documentation
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
[gentoo-dev] Re: USE flag documentation
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
[gentoo-dev] Re: USE flag documentation
Marius Mauch <[EMAIL PROTECTED]> posted [EMAIL PROTECTED], 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 -- [EMAIL PROTECTED] mailing list
