/[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 - (show 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 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