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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download)
Fri Mar 11 19:07:16 2005 UTC (9 years, 4 months ago) by g2boojum
Branch: MAIN
File MIME type: text/plain
new glep

1 GLEP: 34
2 Title: Per-Category metadata.xml Files
3 Version: $Revision: $
4 Author: Ciaran McCreesh <ciaranm@gentoo.org>
5 Last-Modified: $Date: $
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 03-March-2005
10 Post-Date: 03-March-2005
11
12 Abstract
13 ========
14
15 A ``metadata.xml`` file [1]_ is currently used to provide extra metadata
16 (long descriptions, herd and maintainer information) about a package. It
17 is proposed that these files also be used to describe the purpose of a
18 category.
19
20 Motivation
21 ==========
22
23 Category names are short and not entirely clear. Adding arbitrary length
24 long descriptions to categories would provide several advantages:
25
26 * It would clarify the meaning of categories for users, who may not be
27 aware of some of the abbreviations or acronyms we use.
28
29 * With the use of XML ``lang=""`` attributes, it would allow for
30 additional non-English descriptions (simply using longer category names
31 would not allow this).
32
33 * It would help developers better select a relevant category for their
34 package, rather than dumping everything into ``sys-apps`` and
35 ``app-misc`` as is done currently.
36
37 * It would help illustrate which categories are too broad or badly defined
38 in scope, making any future category splits easier.
39
40 Specification
41 =============
42
43 It is proposed that the existing ``metadata.xml`` format [1]_ be used.
44 Even though XML sucks, there is already a framework in place for these
45 files. The filename will be ``blah-misc/metadata.xml``. The character set
46 used shall be UTF-8 for consistency with GLEP 31 [2]_.
47
48 A new top level ``<catmetadata>`` element shall be added to the DTD to
49 distinguish category metadata elements from the existing ``<pkgmetadata>``
50 elements.
51
52 The existing ``<longdescription>`` elements shall be used for
53 descriptions. The ``lang`` attribute shall be used to indicate the human
54 language of the description -- all categories must have at least an
55 English (``en``) description.
56
57 The ``<herd>`` and ``<maintainer>`` elements are not generally relevant at
58 the category level.
59
60
61 Examples
62 --------
63
64 The ``app-vim`` category could use a ``metadata.xml`` file like the
65 following: ::
66
67 <?xml version="1.0" encoding="UTF-8"?>
68 <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
69 <catmetadata>
70 <longdescription lang="en">
71 The app-vim category contains plugins and syntax file
72 packages for the Vim text editor.
73 </longdescription>
74 <longdescription lang="de">
75 Die Kategorie app-vim enthält Plugins und Syntax-Pakete
76 für den Vim Texteditor.
77 </longdescription>
78 </catmetadata>
79
80 Implementation Requirements
81 ---------------------------
82
83 The DTD file would need to be updated to include the ``<catmetadata>``
84 element.
85
86 A metadata file would have to be added to every category in the tree. This
87 could be done over a period of time.
88
89 ``repoman`` checks for category metadata files would not be necessary.
90
91 The "packages.gentoo.org metadata" bug [3]_ would need to be
92 updated to ask for category descriptions as well.
93
94 The metadata documentation [1]_ would require some additions.
95
96 Backwards Compatability
97 =======================
98
99 The metadata DTD will remain backwards compatible.
100
101 The category metadata files will need to be considered "optional until
102 implemented" rather than immediately becoming mandatory.
103
104 References
105 ==========
106
107 .. [1] Gentoo Metadata,
108 (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)
109 .. [2] GLEP 31: Character Sets for Portage Tree Items
110 (http://www.gentoo.org/proj/en/glep/glep-0031.html)
111 .. [3] Gentoo bug 66917
112 (http://bugs.gentoo.org/show_bug.cgi?id=66917)
113
114 Copyright
115 =========
116
117 This document has been placed in the public domain.
118
119 vim: set tw=74 fileencoding=utf-8 :

  ViewVC Help
Powered by ViewVC 1.1.20