From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from parrot.gentoo.org (lists.gentoo.org [156.56.111.196]) by robin.gentoo.org (8.13.3/8.13.3) with ESMTP id j2DFd3t2004838 for ; Sun, 13 Mar 2005 15:39:03 GMT Received: (qmail 13993 invoked by uid 89); 13 Mar 2005 15:39:00 +0000 Received: (qmail 30683 invoked from network); 13 Mar 2005 15:39:00 +0000 Received: from smtp.gentoo.org (134.68.220.30) by lists.gentoo.org with AES256-SHA encrypted SMTP; 13 Mar 2005 15:39:00 +0000 Received: from [62.254.189.226] (helo=snowdrop) by smtp.gentoo.org with esmtpa (Exim 4.43) id 1DAVBE-0007iJ-1O; Sun, 13 Mar 2005 15:39:00 +0000 Received: from localhost ([127.0.0.1] helo=snowdrop) by snowdrop with esmtp (Exim 4.43) id 1DAVAc-0003t1-Mn; Sun, 13 Mar 2005 15:38:22 +0000 Date: Sun, 13 Mar 2005 15:38:16 +0000 From: Ciaran McCreesh To: gentoo-dev@lists.gentoo.org Cc: glep@gentoo.org Subject: [gentoo-dev] GLEP 34: Per-Category metadata.xml Files Message-ID: <20050313153816.56c6f684@snowdrop> X-Mailer: Sylpheed-Claws 1.0.3 (GTK+ 1.2.10; i686-pc-linux-gnu) Precedence: bulk List-Post: , , List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-To: gentoo-dev@gentoo.org Mime-Version: 1.0 Content-Type: multipart/signed; boundary="Signature_Sun__13_Mar_2005_15_38_16_+0000_aLo3v.nUEhdk=MHb"; protocol="application/pgp-signature"; micalg=pgp-sha1 X-Archives-Salt: 992044f7-cd1b-4ff2-9f58-fe960aa4bdb5 X-Archives-Hash: 569ba3aaa43123edb12fedec38ae2aad --Signature_Sun__13_Mar_2005_15_38_16_+0000_aLo3v.nUEhdk=MHb Content-Type: multipart/mixed; boundary=Multipart_Sun__13_Mar_2005_15_38_16_+0000_aBPeyKemthqgkHbI --Multipart_Sun__13_Mar_2005_15_38_16_+0000_aBPeyKemthqgkHbI Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Content-Disposition: inline Attached is an updated GLEP 34 (Per-Category metadata.xml Files) draft. Changes since the last posting are: * clarified the wording and purpose of the catmetadata element * clarified maintainer information elements at category level * wording fixes If there are no further comments, I'd like this to be voted upon on Monday. --=20 Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools) Mail : ciaranm at gentoo.org Web : http://dev.gentoo.org/~ciaranm --Multipart_Sun__13_Mar_2005_15_38_16_+0000_aBPeyKemthqgkHbI Content-Type: text/plain; name=glep-0034.txt Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=glep-0034.txt GLEP: 34 Title: Per-Category metadata.xml Files Version: $Revision: 1.1 $ Author: Ciaran McCreesh Last-Modified: $Date: 2005/03/11 19:07:16 $ Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 11-March-2005 Post-Date: 11-March-2005, 13-March-2005 Abstract =3D=3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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=3D""`` 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 ```` element shall be added to the DTD. This is necessary because the existing ```` 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 ```` 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 ```` and ```` 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: :: The app-vim category contains plugins and syntax file packages for the Vim text editor. Die Kategorie app-vim enth=C3=A4lt Plugins und Syntax-Pakete f=C3=BCr den Vim Texteditor. Implementation Requirements --------------------------- The DTD file would need to be updated to include the ```` 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D .. [1] Gentoo Metadata, (http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=3D2= &chap=3D4) .. [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=3D66917) Copyright =3D=3D=3D=3D=3D=3D=3D=3D=3D This document has been placed in the public domain. .. vim: set tw=3D74 fileencoding=3Dutf-8 : --Multipart_Sun__13_Mar_2005_15_38_16_+0000_aBPeyKemthqgkHbI-- --Signature_Sun__13_Mar_2005_15_38_16_+0000_aLo3v.nUEhdk=MHb Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.6 (GNU/Linux) iD8DBQFCNF5t96zL6DUtXhERAmJQAJ9at/bvH7Q6GILzJaDML6Ml8T9ypwCfeAxQ qEpZeC9F7arsvjRxFcKwCt0= =atDD -----END PGP SIGNATURE----- --Signature_Sun__13_Mar_2005_15_38_16_+0000_aLo3v.nUEhdk=MHb-- -- gentoo-dev@gentoo.org mailing list