GLEP:34

Warning
This GLEP is no longer maintained in the Gentoo Wiki and remains here only as a historical record. Please visit https://www.gentoo.org/glep/glep-0034.html for the current version of this GLEP.

GLEP 34: Per-Category metadata.xml Files
Type	Standards Track
Status	Final
Author	Ciaran McCreesh <ciaranm@gentoo.org>
Editor
Replaces
Replaced by	68 (Package and category metadata)
Requires
Post History

Abstract

A metadata.xml file 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 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 .

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 would need to be updated to ask for category descriptions as well.

The metadata documentation 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.

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/.