Get Gentoo!

GLEP 34: Per-Category metadata.xml Files

Author Ciaran McCreesh <ciaranm@gentoo.org>
Type Standards Track
Status Replaced
Version 1
Created 2005-03-11
Last modified 2017-10-13
Posting history 2005-03-11, 2005-03-13, 2005-05-02
Replaced by 68
GLEP source glep-0034.rst

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.