/[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.5 - (show annotations) (download)
Mon Nov 7 22:26:59 2005 UTC (9 years, 1 month ago) by ciaranm
Branch: MAIN
CVS Tags: HEAD
Changes since 1.4: +4 -4 lines
File MIME type: text/plain
Error occurred while calculating annotation data.
Fix header typos, GLEP 1 compliance

1 GLEP: 34
2 Title: Per-Category metadata.xml Files
3 Version: $Revision: 1.4 $
4 Author: Ciaran McCreesh <ciaranm@gentoo.org>
5 Last-Modified: $Date: 2005/05/02 20:30:24 $
6 Status: Final
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 11-Mar-2005
10 Post-History: 11-Mar-2005, 13-Mar-2005, 2-May-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. This
49 is necessary because the existing ``<pkgmetadata>`` element is not
50 appropriately named, and doing a global rename would be impractical. Using
51 a different element would also permit additional category-specific data to
52 be added at a later date.
53
54 The existing ``<longdescription>`` elements shall be used for
55 descriptions. The ``lang`` attribute shall be used to indicate the human
56 language of the description -- all categories must have at least an
57 English (``en``) description.
58
59 The ``<herd>`` and ``<maintainer>`` elements are not generally relevant at
60 the category level. They may be specified as a fall-back "assume that
61 everything in this category is maintained by these people", but this must
62 not be used as a replacement for proper per-package metadata.
63
64
65 Examples
66 --------
67
68 The ``app-vim`` category could use a ``metadata.xml`` file like the
69 following: ::
70
71 <?xml version="1.0" encoding="UTF-8"?>
72 <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
73 <catmetadata>
74 <longdescription lang="en">
75 The app-vim category contains plugins and syntax file
76 packages for the Vim text editor.
77 </longdescription>
78 <longdescription lang="de">
79 Die Kategorie app-vim enthält Plugins und Syntax-Pakete
80 für den Vim Texteditor.
81 </longdescription>
82 </catmetadata>
83
84 Implementation Requirements
85 ---------------------------
86
87 The DTD file would need to be updated to include the ``<catmetadata>``
88 element.
89
90 A metadata file would have to be added to every category in the tree. This
91 could be done over a period of time.
92
93 ``repoman`` would need a few small changes to be able to handle
94 per-category metadata files.
95
96 The "packages.gentoo.org metadata" bug [3]_ would need to be
97 updated to ask for category descriptions as well.
98
99 The metadata documentation [1]_ would require some additions.
100
101 Backwards Compatibility
102 =======================
103
104 The metadata DTD will remain backwards compatible.
105
106 The category metadata files will need to be considered "optional until
107 implemented" rather than immediately becoming mandatory.
108
109 References
110 ==========
111
112 .. [1] Gentoo Metadata,
113 (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)
114 .. [2] GLEP 31: Character Sets for Portage Tree Items
115 (http://www.gentoo.org/proj/en/glep/glep-0031.html)
116 .. [3] Gentoo bug 66917
117 (http://bugs.gentoo.org/show_bug.cgi?id=66917)
118
119 Copyright
120 =========
121
122 This document has been placed in the public domain.
123
124 .. vim: set tw=74 fileencoding=utf-8 :

  ViewVC Help
Powered by ViewVC 1.1.20