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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (show annotations) (download) (as text)
Thu Jan 25 03:26:26 2007 UTC (7 years, 8 months ago) by antarus
Branch: MAIN
Changes since 1.6: +3 -3 lines
File MIME type: text/html
Fix headers in all current gleps

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 This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6 PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7 to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8 -->
9 <head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 <title>GLEP 34 -- Per-Category metadata.xml Files</title>
13 <style type="text/css">
14
15 /*
16 :Author: David Goodger
17 :Contact: goodger@users.sourceforge.net
18 :date: $Date: 2006/10/10 20:25:14 $
19 :version: $Revision: 1.6 $
20 :copyright: This stylesheet has been placed in the public domain.
21
22 Default cascading style sheet for the PEP HTML output of Docutils.
23 */
24
25 .first {
26 margin-top: 0 }
27
28 .last {
29 margin-bottom: 0 }
30
31 .navigation {
32 width: 100% ;
33 background: #cc99ff ;
34 margin-top: 0px ;
35 margin-bottom: 0px }
36
37 .navigation .navicon {
38 width: 150px ;
39 height: 35px }
40
41 .navigation .textlinks {
42 padding-left: 1em ;
43 text-align: left }
44
45 .navigation td, .navigation th {
46 padding-left: 0em ;
47 padding-right: 0em ;
48 vertical-align: middle }
49
50 .rfc2822 {
51 margin-top: 0.5em ;
52 margin-left: 0.5em ;
53 margin-right: 0.5em ;
54 margin-bottom: 0em }
55
56 .rfc2822 td {
57 text-align: left }
58
59 .rfc2822 th.field-name {
60 text-align: right ;
61 font-family: sans-serif ;
62 padding-right: 0.5em ;
63 font-weight: bold ;
64 margin-bottom: 0em }
65
66 a.toc-backref {
67 text-decoration: none ;
68 color: black }
69
70 body {
71 margin: 0px ;
72 margin-bottom: 1em ;
73 padding: 0px }
74
75 dd {
76 margin-bottom: 0.5em }
77
78 div.section {
79 margin-left: 1em ;
80 margin-right: 1em ;
81 margin-bottom: 1.5em }
82
83 div.section div.section {
84 margin-left: 0em ;
85 margin-right: 0em ;
86 margin-top: 1.5em }
87
88 div.abstract {
89 margin: 2em 5em }
90
91 div.abstract p.topic-title {
92 font-weight: bold ;
93 text-align: center }
94
95 div.attention, div.caution, div.danger, div.error, div.hint,
96 div.important, div.note, div.tip, div.warning {
97 margin: 2em ;
98 border: medium outset ;
99 padding: 1em }
100
101 div.attention p.admonition-title, div.caution p.admonition-title,
102 div.danger p.admonition-title, div.error p.admonition-title,
103 div.warning p.admonition-title {
104 color: red ;
105 font-weight: bold ;
106 font-family: sans-serif }
107
108 div.hint p.admonition-title, div.important p.admonition-title,
109 div.note p.admonition-title, div.tip p.admonition-title {
110 font-weight: bold ;
111 font-family: sans-serif }
112
113 div.figure {
114 margin-left: 2em }
115
116 div.footer, div.header {
117 font-size: smaller }
118
119 div.footer {
120 margin-left: 1em ;
121 margin-right: 1em }
122
123 div.system-messages {
124 margin: 5em }
125
126 div.system-messages h1 {
127 color: red }
128
129 div.system-message {
130 border: medium outset ;
131 padding: 1em }
132
133 div.system-message p.system-message-title {
134 color: red ;
135 font-weight: bold }
136
137 div.topic {
138 margin: 2em }
139
140 h1 {
141 font-family: sans-serif ;
142 font-size: large }
143
144 h2 {
145 font-family: sans-serif ;
146 font-size: medium }
147
148 h3 {
149 font-family: sans-serif ;
150 font-size: small }
151
152 h4 {
153 font-family: sans-serif ;
154 font-style: italic ;
155 font-size: small }
156
157 h5 {
158 font-family: sans-serif;
159 font-size: x-small }
160
161 h6 {
162 font-family: sans-serif;
163 font-style: italic ;
164 font-size: x-small }
165
166 .section hr {
167 width: 75% }
168
169 ol.simple, ul.simple {
170 margin-bottom: 1em }
171
172 ol.arabic {
173 list-style: decimal }
174
175 ol.loweralpha {
176 list-style: lower-alpha }
177
178 ol.upperalpha {
179 list-style: upper-alpha }
180
181 ol.lowerroman {
182 list-style: lower-roman }
183
184 ol.upperroman {
185 list-style: upper-roman }
186
187 p.caption {
188 font-style: italic }
189
190 p.credits {
191 font-style: italic ;
192 font-size: smaller }
193
194 p.label {
195 white-space: nowrap }
196
197 p.topic-title {
198 font-family: sans-serif ;
199 font-weight: bold }
200
201 pre.line-block {
202 font-family: serif ;
203 font-size: 100% }
204
205 pre.literal-block, pre.doctest-block {
206 margin-left: 2em ;
207 margin-right: 2em ;
208 background-color: #eeeeee }
209
210 span.classifier {
211 font-family: sans-serif ;
212 font-style: oblique }
213
214 span.classifier-delimiter {
215 font-family: sans-serif ;
216 font-weight: bold }
217
218 span.interpreted {
219 font-family: sans-serif }
220
221 span.option-argument {
222 font-style: italic }
223
224 span.pre {
225 white-space: pre }
226
227 span.problematic {
228 color: red }
229
230 table {
231 margin-top: 0.5em ;
232 margin-bottom: 0.5em }
233
234 td, th {
235 padding-left: 0.5em ;
236 padding-right: 0.5em ;
237 vertical-align: top }
238
239 td.num {
240 text-align: right }
241
242 th.field-name {
243 font-weight: bold ;
244 text-align: left ;
245 white-space: nowrap }
246
247 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248 font-size: 100% }
249
250 tt {
251 background-color: #eeeeee }
252
253 ul.auto-toc {
254 list-style-type: none }
255
256 </style>
257 </head>
258 <body bgcolor="white">
259 <table class="navigation" cellpadding="0" cellspacing="0"
260 width="100%" border="0">
261 <tr><td class="navicon" width="150" height="35">
262 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
263 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
264 border="0" width="150" height="35" /></a></td>
265 <td class="textlinks" align="left">
266 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
267 [<b><a href="http://www.gentoo.org/proj/en/glep/">GLEP Index</a></b>]
268 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0034.txt">GLEP Source</a></b>]
269 </td></tr></table>
270 <table class="rfc2822 docutils field-list" frame="void" rules="none">
271 <col class="field-name" />
272 <col class="field-body" />
273 <tbody valign="top">
274 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">34</td>
275 </tr>
276 <tr class="field"><th class="field-name">Title:</th><td class="field-body">Per-Category metadata.xml Files</td>
277 </tr>
278 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.5</td>
279 </tr>
280 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Ciaran McCreesh &lt;ciaranm&#32;&#97;t&#32;gentoo.org&gt;</td>
281 </tr>
282 <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-0034.txt?cvsroot=gentoo">2005/11/07 22:26:59</a></td>
283 </tr>
284 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
285 </tr>
286 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
287 </tr>
288 <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>
289 </tr>
290 <tr class="field"><th class="field-name">Created:</th><td class="field-body">11-Mar-2005</td>
291 </tr>
292 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">11-Mar-2005, 13-Mar-2005, 2-May-2005</td>
293 </tr>
294 </tbody>
295 </table>
296 <hr />
297 <div class="contents topic">
298 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299 <ul class="simple">
300 <li><a class="reference" href="#abstract" id="id9" name="id9">Abstract</a></li>
301 <li><a class="reference" href="#motivation" id="id10" name="id10">Motivation</a></li>
302 <li><a class="reference" href="#specification" id="id11" name="id11">Specification</a><ul>
303 <li><a class="reference" href="#examples" id="id12" name="id12">Examples</a></li>
304 <li><a class="reference" href="#implementation-requirements" id="id13" name="id13">Implementation Requirements</a></li>
305 </ul>
306 </li>
307 <li><a class="reference" href="#backwards-compatibility" id="id14" name="id14">Backwards Compatibility</a></li>
308 <li><a class="reference" href="#references" id="id15" name="id15">References</a></li>
309 <li><a class="reference" href="#copyright" id="id16" name="id16">Copyright</a></li>
310 </ul>
311 </div>
312 <div class="section">
313 <h1><a class="toc-backref" href="#id9" id="abstract" name="abstract">Abstract</a></h1>
314 <p>A <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> file <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a> is currently used to provide extra metadata
315 (long descriptions, herd and maintainer information) about a package. It
316 is proposed that these files also be used to describe the purpose of a
317 category.</p>
318 </div>
319 <div class="section">
320 <h1><a class="toc-backref" href="#id10" id="motivation" name="motivation">Motivation</a></h1>
321 <p>Category names are short and not entirely clear. Adding arbitrary length
322 long descriptions to categories would provide several advantages:</p>
323 <ul class="simple">
324 <li>It would clarify the meaning of categories for users, who may not be
325 aware of some of the abbreviations or acronyms we use.</li>
326 <li>With the use of XML <tt class="docutils literal"><span class="pre">lang=&quot;&quot;</span></tt> attributes, it would allow for
327 additional non-English descriptions (simply using longer category names
328 would not allow this).</li>
329 <li>It would help developers better select a relevant category for their
330 package, rather than dumping everything into <tt class="docutils literal"><span class="pre">sys-apps</span></tt> and
331 <tt class="docutils literal"><span class="pre">app-misc</span></tt> as is done currently.</li>
332 <li>It would help illustrate which categories are too broad or badly defined
333 in scope, making any future category splits easier.</li>
334 </ul>
335 </div>
336 <div class="section">
337 <h1><a class="toc-backref" href="#id11" id="specification" name="specification">Specification</a></h1>
338 <p>It is proposed that the existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> format <a class="footnote-reference" href="#id6" id="id2" name="id2">[1]</a> be used.
339 Even though XML sucks, there is already a framework in place for these
340 files. The filename will be <tt class="docutils literal"><span class="pre">blah-misc/metadata.xml</span></tt>. The character set
341 used shall be UTF-8 for consistency with GLEP 31 <a class="footnote-reference" href="#id7" id="id3" name="id3">[2]</a>.</p>
342 <p>A new top level <tt class="docutils literal"><span class="pre">&lt;catmetadata&gt;</span></tt> element shall be added to the DTD. This
343 is necessary because the existing <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> element is not
344 appropriately named, and doing a global rename would be impractical. Using
345 a different element would also permit additional category-specific data to
346 be added at a later date.</p>
347 <p>The existing <tt class="docutils literal"><span class="pre">&lt;longdescription&gt;</span></tt> elements shall be used for
348 descriptions. The <tt class="docutils literal"><span class="pre">lang</span></tt> attribute shall be used to indicate the human
349 language of the description -- all categories must have at least an
350 English (<tt class="docutils literal"><span class="pre">en</span></tt>) description.</p>
351 <p>The <tt class="docutils literal"><span class="pre">&lt;herd&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;maintainer&gt;</span></tt> elements are not generally relevant at
352 the category level. They may be specified as a fall-back &quot;assume that
353 everything in this category is maintained by these people&quot;, but this must
354 not be used as a replacement for proper per-package metadata.</p>
355 <div class="section">
356 <h2><a class="toc-backref" href="#id12" id="examples" name="examples">Examples</a></h2>
357 <p>The <tt class="docutils literal"><span class="pre">app-vim</span></tt> category could use a <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> file like the
358 following:</p>
359 <pre class="literal-block">
360 &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
361 &lt;!DOCTYPE catmetadata SYSTEM &quot;http://www.gentoo.org/dtd/metadata.dtd&quot;&gt;
362 &lt;catmetadata&gt;
363 &lt;longdescription lang=&quot;en&quot;&gt;
364 The app-vim category contains plugins and syntax file
365 packages for the Vim text editor.
366 &lt;/longdescription&gt;
367 &lt;longdescription lang=&quot;de&quot;&gt;
368 Die Kategorie app-vim enthält Plugins und Syntax-Pakete
369 für den Vim Texteditor.
370 &lt;/longdescription&gt;
371 &lt;/catmetadata&gt;
372 </pre>
373 </div>
374 <div class="section">
375 <h2><a class="toc-backref" href="#id13" id="implementation-requirements" name="implementation-requirements">Implementation Requirements</a></h2>
376 <p>The DTD file would need to be updated to include the <tt class="docutils literal"><span class="pre">&lt;catmetadata&gt;</span></tt>
377 element.</p>
378 <p>A metadata file would have to be added to every category in the tree. This
379 could be done over a period of time.</p>
380 <p><tt class="docutils literal"><span class="pre">repoman</span></tt> would need a few small changes to be able to handle
381 per-category metadata files.</p>
382 <p>The &quot;packages.gentoo.org metadata&quot; bug <a class="footnote-reference" href="#id8" id="id4" name="id4">[3]</a> would need to be
383 updated to ask for category descriptions as well.</p>
384 <p>The metadata documentation <a class="footnote-reference" href="#id6" id="id5" name="id5">[1]</a> would require some additions.</p>
385 </div>
386 </div>
387 <div class="section">
388 <h1><a class="toc-backref" href="#id14" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
389 <p>The metadata DTD will remain backwards compatible.</p>
390 <p>The category metadata files will need to be considered &quot;optional until
391 implemented&quot; rather than immediately becoming mandatory.</p>
392 </div>
393 <div class="section">
394 <h1><a class="toc-backref" href="#id15" id="references" name="references">References</a></h1>
395 <table class="docutils footnote" frame="void" id="id6" rules="none">
396 <colgroup><col class="label" /><col /></colgroup>
397 <tbody valign="top">
398 <tr><td class="label"><a name="id6">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id5">3</a>)</em> Gentoo Metadata,
399 (<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>
400 </tbody>
401 </table>
402 <table class="docutils footnote" frame="void" id="id7" rules="none">
403 <colgroup><col class="label" /><col /></colgroup>
404 <tbody valign="top">
405 <tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[2]</a></td><td>GLEP 31: Character Sets for Portage Tree Items
406 (<a class="reference" href="http://www.gentoo.org/proj/en/glep/glep-0031.html">http://www.gentoo.org/proj/en/glep/glep-0031.html</a>)</td></tr>
407 </tbody>
408 </table>
409 <table class="docutils footnote" frame="void" id="id8" rules="none">
410 <colgroup><col class="label" /><col /></colgroup>
411 <tbody valign="top">
412 <tr><td class="label"><a class="fn-backref" href="#id4" name="id8">[3]</a></td><td>Gentoo bug 66917
413 (<a class="reference" href="http://bugs.gentoo.org/show_bug.cgi?id=66917">http://bugs.gentoo.org/show_bug.cgi?id=66917</a>)</td></tr>
414 </tbody>
415 </table>
416 </div>
417 <div class="section">
418 <h1><a class="toc-backref" href="#id16" id="copyright" name="copyright">Copyright</a></h1>
419 <p>This document has been placed in the public domain.</p>
420 <!-- vim: set tw=74 fileencoding=utf-8 : -->
421 </div>
422
423 </div>
424 <div class="footer">
425 <hr class="footer" />
426 <a class="reference" href="glep-0034.txt">View document source</a>.
427 Generated on: 2006-10-10 20:23 UTC.
428 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.
429
430 </div>
431 </body>
432 </html>

  ViewVC Help
Powered by ViewVC 1.1.20