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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download) (as text)
Thu Jun 5 05:55:22 2008 UTC (6 years, 1 month ago) by dev-zero
Branch: MAIN
File MIME type: text/html
Added html for GLEP-0056

1 dev-zero 1.1 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4    
5     <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7     <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8     <title>GLEP 56 -- USE flag descriptions in metadata</title>
9     <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10     </head>
11     <body bgcolor="white">
12     <table class="navigation" cellpadding="0" cellspacing="0"
13     width="100%" border="0">
14     <tr><td class="navicon" width="150" height="35">
15     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17     border="0" width="150" height="35" /></a></td>
18     <td class="textlinks" align="left">
19     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20     [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21     [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0056.txt">GLEP Source</a></b>]
22     </td></tr></table>
23     <table class="rfc2822 docutils field-list" frame="void" rules="none">
24     <col class="field-name" />
25     <col class="field-body" />
26     <tbody valign="top">
27     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">56</td>
28     </tr>
29     <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag descriptions in metadata</td>
30     </tr>
31     <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
32     </tr>
33     <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0056.txt?cvsroot=gentoo">2008/06/05 05:54:10</a></td>
34     </tr>
35     <tr class="field"><th class="field-name">Author:</th><td class="field-body">Doug Goldstein &lt;cardoe&#32;&#97;t&#32;gentoo.org&gt;</td>
36     </tr>
37     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
38     </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </tr>
41     <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
42     </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">03-Jun-2008</td>
44     </tr>
45     <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">05-Jun-2008</td>
46     </tr>
47     </tbody>
48     </table>
49     <hr />
50     <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52     <ul class="simple">
53     <li><a class="reference" href="#abstract" id="id12" name="id12">Abstract</a></li>
54     <li><a class="reference" href="#motivation" id="id13" name="id13">Motivation</a></li>
55     <li><a class="reference" href="#specification" id="id14" name="id14">Specification</a></li>
56     <li><a class="reference" href="#credits" id="id15" name="id15">Credits</a></li>
57     <li><a class="reference" href="#references" id="id16" name="id16">References</a></li>
58     <li><a class="reference" href="#copyright" id="id17" name="id17">Copyright</a></li>
59     </ul>
60     </div>
61     <div class="section">
62     <h1><a class="toc-backref" href="#id12" id="abstract" name="abstract">Abstract</a></h1>
63     <p>This GLEP proposes to add per-package USE flag descriptions to each package's
64     metadata.</p>
65     </div>
66     <div class="section">
67     <h1><a class="toc-backref" href="#id13" id="motivation" name="motivation">Motivation</a></h1>
68     <p>Gives Gentoo users the ability to better identify how USE flags affect their
69     installations of a given package. For example, many global USE flags have very
70     generic descriptions but no specifics on how it affects a certain package.
71     Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
72     flag. Does this flag mean you won't be able to print jpeg files? You can print
73     them directly? It's interface won't use jpeg files.</p>
74     <blockquote>
75     <ul class="simple">
76     <li>Motivator References: <a class="footnote-reference" href="#motivators1" id="id1" name="id1">[6]</a>, <a class="footnote-reference" href="#motivators2" id="id2" name="id2">[7]</a>, <a class="footnote-reference" href="#motivators3" id="id3" name="id3">[8]</a>,
77     and <a class="footnote-reference" href="#motivators4" id="id4" name="id4">[9]</a></li>
78     </ul>
79     </blockquote>
80     </div>
81     <div class="section">
82     <h1><a class="toc-backref" href="#id14" id="specification" name="specification">Specification</a></h1>
83     <p>This GLEP proposes the addition of <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag that is only allowed to
84     appear inside of a <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> XML tag.</p>
85     <blockquote>
86     <ul>
87     <li><p class="first">Inside the <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag, the <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag is allowed to appear
88     once per USE flag as specified by the <tt class="docutils literal"><span class="pre">'name'</span></tt> attribute with the
89     following exception:</p>
90     <ul class="simple">
91     <li>The <tt class="docutils literal"><span class="pre">'restrict'</span></tt> atttribute can limit to specific versions of the
92     package, where the attribute value must be a valid CPV as defined by the
93     <cite>Package Manager Specification</cite> <a class="footnote-reference" href="#pms" id="id5" name="id5">[4]</a>. This follows the current behavior
94     of the <tt class="docutils literal"><span class="pre">'restrict'</span></tt> attribute in metadata.xml.<ul>
95     <li>The <tt class="docutils literal"><span class="pre">restrict</span></tt> attribute follows the documented <tt class="docutils literal"><span class="pre">restrict</span></tt>
96     attribute in the <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id6" name="id6">[5]</a>.</li>
97     <li>e.g. A USE flag may have one behavior for version 0.1 of a package,
98     while version 0.2, the USE flag may differ slightly.</li>
99     </ul>
100     </li>
101     </ul>
102     </li>
103     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag requires a 'name' attribute which is the full USE
104     flag name as it would appear in the IUSE section of the ebuild.</p>
105     <blockquote>
106     <ul class="simple">
107     <li>e.g. &quot;video_cards_i810&quot; or &quot;alsa&quot;</li>
108     </ul>
109     </blockquote>
110     </li>
111     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag allows 0 or more nested <tt class="docutils literal"><span class="pre">&lt;pkg&gt;</span></tt> XML tags whose
112     character data is a valid CP or CPV as defined by the
113     <cite>Package Manager Specification</cite> <a class="footnote-reference" href="#pms" id="id7" name="id7">[4]</a>.</p>
114     </li>
115     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag allows 0 or more nested <tt class="docutils literal"><span class="pre">&lt;cat&gt;</span></tt> XML tags whose
116     character data is a valid category.</p>
117     </li>
118     <li><p class="first">The <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag may appear multiple times inside of the
119     <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> XML tag if and only if it contains a different <tt class="docutils literal"><span class="pre">'lang'</span></tt>
120     attribute value.</p>
121     <ul class="simple">
122     <li>The <tt class="docutils literal"><span class="pre">lang</span></tt> attribute follows the documented <tt class="docutils literal"><span class="pre">lang</span></tt> attribute in the
123     <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id8" name="id8">[5]</a>.</li>
124     <li>The default <tt class="docutils literal"><span class="pre">'lang'</span></tt> attribute value is &quot;C&quot;, which is equivilent to &quot;en&quot;.</li>
125     </ul>
126     </li>
127     </ul>
128     </blockquote>
129     <p>Documentation for the Developer Manual and the metadata.dtd can be found in
130     Gentoo's Bugzilla <a class="footnote-reference" href="#use-flag-metadata-bug" id="id9" name="id9">[1]</a> bug #199788.</p>
131     <p>The following are two concrete examples in tree, <a class="footnote-reference" href="#use-flag-metadata-example1" id="id10" name="id10">[2]</a>
132     and <a class="footnote-reference" href="#use-flag-metadata-example2" id="id11" name="id11">[3]</a>.</p>
133     <p>And the following is an embedded example and not from a real package:</p>
134     <pre class="literal-block">
135     &lt;use&gt;
136     &lt;flag name='acpi'&gt;Enables HAL to attempt to read from
137     /proc/acpi/event, if unavailable, HAL will read events from
138     &lt;pkg&gt;sys-power/acpid&lt;/pkg&gt;. If you need multiple acpi readers,
139     ensure acpid is in your default runlevel
140     (rc-update add acpid default) along with HAL. This will also
141     enable HAL to read Toshiba and IBM acpi events which do not
142     get sent via /proc/acpi/event&lt;/flag&gt;
143     &lt;flag name='spell'&gt;Enables spell checking capability using
144     dictionaries found in &lt;cat&gt;app-dict&lt;/cat&gt;&lt;/flag&gt;
145     &lt;/use&gt;
146     </pre>
147     </div>
148     <div class="section">
149     <h1><a class="toc-backref" href="#id15" id="credits" name="credits">Credits</a></h1>
150     <p>Thanks to the following persons for their input on or related to this GLEP
151     (even though they might not have known it):
152     Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
153     Steve Dibb (beandog), and Tiziano Müller (dev-zero)</p>
154     </div>
155     <div class="section">
156     <h1><a class="toc-backref" href="#id16" id="references" name="references">References</a></h1>
157     <table class="docutils footnote" frame="void" id="use-flag-metadata-bug" rules="none">
158     <colgroup><col class="label" /><col /></colgroup>
159     <tbody valign="top">
160     <tr><td class="label"><a class="fn-backref" href="#id9" name="use-flag-metadata-bug">[1]</a></td><td><a class="reference" href="http://bugs.gentoo.org/show_bug.cgi?id=199788">http://bugs.gentoo.org/show_bug.cgi?id=199788</a></td></tr>
161     </tbody>
162     </table>
163     <table class="docutils footnote" frame="void" id="use-flag-metadata-example1" rules="none">
164     <colgroup><col class="label" /><col /></colgroup>
165     <tbody valign="top">
166     <tr><td class="label"><a class="fn-backref" href="#id10" name="use-flag-metadata-example1">[2]</a></td><td><a class="reference" href="http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup">http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup</a></td></tr>
167     </tbody>
168     </table>
169     <table class="docutils footnote" frame="void" id="use-flag-metadata-example2" rules="none">
170     <colgroup><col class="label" /><col /></colgroup>
171     <tbody valign="top">
172     <tr><td class="label"><a class="fn-backref" href="#id11" name="use-flag-metadata-example2">[3]</a></td><td><a class="reference" href="http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup">http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup</a></td></tr>
173     </tbody>
174     </table>
175     <table class="docutils footnote" frame="void" id="pms" rules="none">
176     <colgroup><col class="label" /><col /></colgroup>
177     <tbody valign="top">
178     <tr><td class="label"><a name="pms">[4]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> <a class="reference" href="http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary">http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary</a></td></tr>
179     </tbody>
180     </table>
181     <table class="docutils footnote" frame="void" id="devhandbook" rules="none">
182     <colgroup><col class="label" /><col /></colgroup>
183     <tbody valign="top">
184     <tr><td class="label"><a name="devhandbook">[5]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id8">2</a>)</em> <a class="reference" href="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4">http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4</a></td></tr>
185     </tbody>
186     </table>
187     <table class="docutils footnote" frame="void" id="motivators1" rules="none">
188     <colgroup><col class="label" /><col /></colgroup>
189     <tbody valign="top">
190     <tr><td class="label"><a class="fn-backref" href="#id1" name="motivators1">[6]</a></td><td><a class="reference" href="http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata">http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata</a></td></tr>
191     </tbody>
192     </table>
193     <table class="docutils footnote" frame="void" id="motivators2" rules="none">
194     <colgroup><col class="label" /><col /></colgroup>
195     <tbody valign="top">
196     <tr><td class="label"><a class="fn-backref" href="#id2" name="motivators2">[7]</a></td><td><a class="reference" href="http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/">http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/</a></td></tr>
197     </tbody>
198     </table>
199     <table class="docutils footnote" frame="void" id="motivators3" rules="none">
200     <colgroup><col class="label" /><col /></colgroup>
201     <tbody valign="top">
202     <tr><td class="label"><a class="fn-backref" href="#id3" name="motivators3">[8]</a></td><td><a class="reference" href="http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/">http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/</a></td></tr>
203     </tbody>
204     </table>
205     <table class="docutils footnote" frame="void" id="motivators4" rules="none">
206     <colgroup><col class="label" /><col /></colgroup>
207     <tbody valign="top">
208     <tr><td class="label"><a class="fn-backref" href="#id4" name="motivators4">[9]</a></td><td><a class="reference" href="http://technicalpickles.com/posts/pidgin-idle-time">http://technicalpickles.com/posts/pidgin-idle-time</a></td></tr>
209     </tbody>
210     </table>
211     </div>
212     <div class="section">
213     <h1><a class="toc-backref" href="#id17" id="copyright" name="copyright">Copyright</a></h1>
214     <p>This document is placed into the public domain.</p>
215     <!-- vim: set ft=glep tw=72 : -->
216     </div>
217    
218     </div>
219     <div class="footer">
220     <hr class="footer" />
221     <a class="reference" href="glep-0056.txt">View document source</a>.
222     Generated on: 2008-06-05 05:54 UTC.
223     Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
224    
225     </div>
226     </body>
227     </html>

  ViewVC Help
Powered by ViewVC 1.1.20