/[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.4 - (hide annotations) (download)
Mon May 2 20:30:24 2005 UTC (9 years, 7 months ago) by g2boojum
Branch: MAIN
Changes since 1.3: +4 -4 lines
File MIME type: text/plain
marking final

1 g2boojum 1.1 GLEP: 34
2     Title: Per-Category metadata.xml Files
3 g2boojum 1.4 Version: $Revision: 1.3 $
4 g2boojum 1.1 Author: Ciaran McCreesh <ciaranm@gentoo.org>
5 g2boojum 1.4 Last-Modified: $Date: 2005/03/17 23:57:56 $
6     Status: Final
7 g2boojum 1.1 Type: Standards Track
8     Content-Type: text/x-rst
9 g2boojum 1.2 Created: 11-March-2005
10 g2boojum 1.4 Post-Date: 11-March-2005, 13-March-2005, 2-May-2005
11 g2boojum 1.1
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 g2boojum 1.2 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 g2boojum 1.1
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 g2boojum 1.2 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 g2boojum 1.1
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 g2boojum 1.2 ``repoman`` would need a few small changes to be able to handle
94     per-category metadata files.
95 g2boojum 1.1
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 g2boojum 1.2 Backwards Compatibility
102 g2boojum 1.1 =======================
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 g2boojum 1.2 .. vim: set tw=74 fileencoding=utf-8 :

  ViewVC Help
Powered by ViewVC 1.1.20