--- xml/htdocs/proj/en/glep/glep-0056.html 2008/06/05 05:55:22 1.1 +++ xml/htdocs/proj/en/glep/glep-0056.html 2008/07/10 18:24:24 1.2 @@ -28,9 +28,9 @@ Title:USE flag descriptions in metadata -Version:1.1 +Version:1.2 -Last-Modified:2008/06/05 05:54:10 +Last-Modified:2008/07/10 18:15:05 Author:Doug Goldstein <cardoe at gentoo.org> @@ -42,7 +42,7 @@ Created:03-Jun-2008 -Post-History:05-Jun-2008 +Post-History:13-Jun-2008 @@ -50,21 +50,22 @@

Contents

-

Abstract

+

Abstract

This GLEP proposes to add per-package USE flag descriptions to each package's metadata.

-

Motivation

+

Motivation

Gives Gentoo users the ability to better identify how USE flags affect their installations of a given package. For example, many global USE flags have very generic descriptions but no specifics on how it affects a certain package. @@ -79,7 +80,7 @@

-

Specification

+

Specification

This GLEP proposes the addition of <use> XML tag that is only allowed to appear inside of a <pkgmetadata> XML tag.

@@ -90,10 +91,8 @@

Documentation for the Developer Manual and the metadata.dtd can be found in -Gentoo's Bugzilla [1] bug #199788.

-

The following are two concrete examples in tree, [2] -and [3].

+Gentoo's Bugzilla [1] bug #199788.

+

The following are two concrete examples in tree, [2] +and [3].

And the following is an embedded example and not from a real package:

 <use>
@@ -146,42 +144,42 @@
 
-

Credits

+

Credits

Thanks to the following persons for their input on or related to this GLEP (even though they might not have known it): Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj), Steve Dibb (beandog), and Tiziano Müller (dev-zero)

-

References

+

References

- +
[1]http://bugs.gentoo.org/show_bug.cgi?id=199788
[1]http://bugs.gentoo.org/show_bug.cgi?id=199788
- +
[2]http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
[2]http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
- +
[3]http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
[3]http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
- +
- +
[4](1, 2) http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary
[4](1, 2) http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
- +
- +
[5](1, 2) http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
[5]http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
@@ -210,6 +208,24 @@
+

Backwards Compatibility

+

No changes are necessary to existing metadata.xml files. Information in +the new tags is not mandatory. Tools that currently read metadata.xml +files may break if written poorly, while well written tools should just ignore +the additional elements. Tools which are capable of handling the new tags +should prefer their data over use.desc and use.local.desc.

+

USE flags still must be defined in use.desc or use.local.desc. If the +USE flag is not found in either use.desc or use.local.desc, the +information contained within the new tags in metadata.xml must be ignored +and QA tools should warn as they currently do.

+

Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove +the use.local.desc file from CVS and it will be auto-generated for rsync. +This will ensure that backwards compatibility is not broken for users of +non-CVS trees. At this time, QA tools will need to be updated to verify the +contents of metadata.xml containing the necessary tags which would appear +in use.local.desc.

+
+

Copyright

This document is placed into the public domain.

@@ -219,7 +235,7 @@