/[gentoo]/xml/htdocs/proj/en/glep/glep-0056.txt
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0056.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download)
Thu Jun 5 05:54:10 2008 UTC (6 years, 4 months ago) by dev-zero
Branch: MAIN
File MIME type: text/plain
Added GLEP-0056 as requested by Cardoe. Minor corrections (spelling of names, vim-syntax line, post-date) made.

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 :

  ViewVC Help
Powered by ViewVC 1.1.20