en/glep/glep-0034.txt

GLEP: 34
Title: Per-Category metadata.xml Files
Version: $Revision: 1.3 $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2005/03/17 23:57:56 $
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 11-March-2005
Post-Date: 11-March-2005, 13-March-2005, 2-May-2005

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,
       (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)
.. [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 document has been placed in the public domain.

.. vim: set tw=74 fileencoding=utf-8 :
1	GLEP: 34
2	Title: Per-Category metadata.xml Files
3	Version: $Revision: 1.3 $
4	Author: Ciaran McCreesh <ciaranm@gentoo.org>
5	Last-Modified: $Date: 2005/03/17 23:57:56 $
6	Status: Final
7	Type: Standards Track
8	Content-Type: text/x-rst
9	Created: 11-March-2005
10	Post-Date: 11-March-2005, 13-March-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 :