/[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 - (hide annotations) (download)
Fri Mar 11 19:07:16 2005 UTC (9 years, 6 months ago) by g2boojum
Branch: MAIN
File MIME type: text/plain
new glep

1 g2boojum 1.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