en/glep/glep-0056.txt

GLEP: 56
Title: USE flag descriptions in metadata
Version: $Revision: $
Last-Modified: $Date: $
Author: Doug Goldstein <cardoe@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 03-Jun-2008
Post-History: 05-Jun-2008

Abstract
========

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


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.
Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
flag. Does this flag mean you won't be able to print jpeg files? You can print
them directly? It's interface won't use jpeg files.

 - Motivator References: [#motivators1]_, [#motivators2]_, [#motivators3]_,
   and [#motivators4]_


Specification
=============

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

 - Inside the ``<use>`` XML tag, the ``<flag>`` XML tag is allowed to appear
   once per USE flag as specified by the ``'name'`` attribute with the
   following exception:
   
   * The ``'restrict'`` atttribute can limit to specific versions of the
     package, where the attribute value must be a valid CPV as defined by the
     `Package Manager Specification` [#pms]_.  This follows the current behavior
     of the ``'restrict'`` attribute in metadata.xml. 
     
     - The ``restrict`` attribute follows the documented ``restrict``
       attribute in the `Gentoo Developer Handbook` [#devhandbook]_.

     - e.g. A USE flag may have one behavior for version 0.1 of a package,
       while version 0.2, the USE flag may differ slightly.

 - Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE
   flag name as it would appear in the IUSE section of the ebuild.
    
    * e.g. "video_cards_i810" or "alsa"

 - Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose
   character data is a valid CP or CPV as defined by the
   `Package Manager Specification` [#pms]_.

 - Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose
   character data is a valid category.

 - The ``<use>`` XML tag may appear multiple times inside of the
   ``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'``
   attribute value.

   * The ``lang`` attribute follows the documented ``lang`` attribute in the
     `Gentoo Developer Handbook` [#devhandbook]_.

   * The default ``'lang'`` attribute value is "C", which is equivilent to "en".

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

The following are two concrete examples in tree, [#use-flag-metadata-example1]_
and [#use-flag-metadata-example2]_.

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

        <use>
                <flag name='acpi'>Enables HAL to attempt to read from
                /proc/acpi/event, if unavailable, HAL will read events from
                <pkg>sys-power/acpid</pkg>. If you need multiple acpi readers,
                ensure acpid is in your default runlevel
                (rc-update add acpid default) along with HAL. This will also
                enable HAL to read Toshiba and IBM acpi events which do not
                get sent via /proc/acpi/event</flag>
                <flag name='spell'>Enables spell checking capability using
                dictionaries found in <cat>app-dict</cat></flag>
        </use>


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
==========

.. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788

.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup

.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup 

.. [#pms] http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary

.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4

.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata

.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/

.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/

.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time

Copyright
=========

This document is placed into the public domain.

.. vim: set ft=glep tw=72 :

1	dev-zero	1.1	GLEP: 56
2			Title: USE flag descriptions in metadata
3			Version: $Revision: $
4			Last-Modified: $Date: $
5			Author: Doug Goldstein <cardoe@gentoo.org>
6			Status: Draft
7			Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 03-Jun-2008
10			Post-History: 05-Jun-2008
11
12			Abstract
13			========
14
15			This GLEP proposes to add per-package USE flag descriptions to each package's
16			metadata.
17
18
19			Motivation
20			==========
21
22			Gives Gentoo users the ability to better identify how USE flags affect their
23			installations of a given package. For example, many global USE flags have very
24			generic descriptions but no specifics on how it affects a certain package.
25			Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
26			flag. Does this flag mean you won't be able to print jpeg files? You can print
27			them directly? It's interface won't use jpeg files.
28
29			- Motivator References: [#motivators1]_, [#motivators2]_, [#motivators3]_,
30			and [#motivators4]_
31
32
33			Specification
34			=============
35
36			This GLEP proposes the addition of ``<use>`` XML tag that is only allowed to
37			appear inside of a ``<pkgmetadata>`` XML tag.
38
39			- Inside the ``<use>`` XML tag, the ``<flag>`` XML tag is allowed to appear
40			once per USE flag as specified by the ``'name'`` attribute with the
41			following exception:
42
43			* The ``'restrict'`` atttribute can limit to specific versions of the
44			package, where the attribute value must be a valid CPV as defined by the
45			`Package Manager Specification` [#pms]_. This follows the current behavior
46			of the ``'restrict'`` attribute in metadata.xml.
47
48			- The ``restrict`` attribute follows the documented ``restrict``
49			attribute in the `Gentoo Developer Handbook` [#devhandbook]_.
50
51			- e.g. A USE flag may have one behavior for version 0.1 of a package,
52			while version 0.2, the USE flag may differ slightly.
53
54			- Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE
55			flag name as it would appear in the IUSE section of the ebuild.
56
57			* e.g. "video_cards_i810" or "alsa"
58
59			- Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose
60			character data is a valid CP or CPV as defined by the
61			`Package Manager Specification` [#pms]_.
62
63			- Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose
64			character data is a valid category.
65
66			- The ``<use>`` XML tag may appear multiple times inside of the
67			``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'``
68			attribute value.
69
70			* The ``lang`` attribute follows the documented ``lang`` attribute in the
71			`Gentoo Developer Handbook` [#devhandbook]_.
72
73			* The default ``'lang'`` attribute value is "C", which is equivilent to "en".
74
75			Documentation for the Developer Manual and the metadata.dtd can be found in
76			Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.
77
78			The following are two concrete examples in tree, [#use-flag-metadata-example1]_
79			and [#use-flag-metadata-example2]_.
80
81			And the following is an embedded example and not from a real package::
82
83			<use>
84			<flag name='acpi'>Enables HAL to attempt to read from
85			/proc/acpi/event, if unavailable, HAL will read events from
86			<pkg>sys-power/acpid</pkg>. If you need multiple acpi readers,
87			ensure acpid is in your default runlevel
88			(rc-update add acpid default) along with HAL. This will also
89			enable HAL to read Toshiba and IBM acpi events which do not
90			get sent via /proc/acpi/event</flag>
91			<flag name='spell'>Enables spell checking capability using
92			dictionaries found in <cat>app-dict</cat></flag>
93			</use>
94
95
96
97			Credits
98			=======
99
100			Thanks to the following persons for their input on or related to this GLEP
101			(even though they might not have known it):
102			Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
103			Steve Dibb (beandog), and Tiziano Müller (dev-zero)
104
105
106			References
107			==========
108
109			.. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788
110
111			.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
112
113			.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
114
115			.. [#pms] http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary
116
117			.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
118
119			.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata
120
121			.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/
122
123			.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/
124
125			.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time
126
127			Copyright
128			=========
129
130			This document is placed into the public domain.
131
132			.. vim: set ft=glep tw=72 :
133