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