Add information about specifying slots and subslots in the metadata. Also, update the section according to the specifications in GLEP 68, clarify some of the tags better, and reorder the tags to improve the flow of the text.
Signed-off-by: Göktürk Yüksek <gokt...@binghamton.edu> --- ebuild-writing/misc-files/metadata/text.xml | 140 ++++++++++++++++++---------- 1 file changed, 93 insertions(+), 47 deletions(-) diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml index 31ec926..3d135a6 100644 --- a/ebuild-writing/misc-files/metadata/text.xml +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -14,7 +14,15 @@ package or category. <body> <p> -A <path>metadata.xml</path> file can contain a number of tags: +A metadata file follows the syntax defined in +<uri link="https://wiki.gentoo.org/wiki/GLEP:68";>GLEP 68</uri>. +The character set <b>must</b> be UTF-8 as specified by +<uri link="https://wiki.gentoo.org/wiki/GLEP:31";>GLEP 31</uri>. +</p> + +<p> +The following table summarizes the tags that may appear in a +metadata.xml: </p> <table> @@ -24,28 +32,41 @@ A <path>metadata.xml</path> file can contain a number of tags: </tr> <tr> <ti> + <brite><catmetadata></brite> + </ti> + <ti> + This is the root element of the <path>metadata.xml</path> file for + categories. It has no attributes. It contains a number of + <brite><longdescription></brite> tags, each for a different + language. + </ti> +</tr> +<tr> + <ti> <brite><pkgmetadata></brite> </ti> <ti> This is the root element of the <path>metadata.xml</path> file for packages. It has no attributes. The following subtags are allowed: - <brite><maintainer></brite>, <brite><longdescription></brite>, + <brite><maintainer></brite>, + <brite><slots></brite>, <brite><use></brite>, and <brite><upstream></brite>. + While all the subtags are optional, <upstream> may + appear at most once. </ti> </tr> <tr> + <ti><brite><longdescription></brite></ti> <ti> - <brite><catmetadata></brite> - </ti> - <ti> - This is the root element of the <path>metadata.xml</path> file for - categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34";>GLEP 34</uri>. - It has no attributes. It contains a number of - <brite><longdescription></brite> tags, each for a different - language. + This tag contains a description for a category or a package. For + packages, it is used to augment the + <uri link="::ebuild-writing/variables#ebuild-defined-variables"> + DESCRIPTION</uri> field in the ebuilds themselves. This tag has + two optional subtags: <brite><pkg></brite> and + <brite><cat></brite>. </ti> </tr> <tr> @@ -83,11 +104,25 @@ A <path>metadata.xml</path> file can contain a number of tags: </ti> </tr> <tr> - <ti><brite><longdescription></brite></ti> + <ti><brite><slots></brite></ti> + <ti> + This tag describes the + <uri link="::general-concepts/slotting">slots</uri> of a package. + It has two optional subtags: <slot> and <subslots>. + </ti> +</tr> +<tr> + <ti><brite><slot></brite></ti> + <ti> + This contains information for a particular slot. The <c>name</c> + attribute is mandatory and specifies the name of the slot. + </ti> +</tr> +<tr> + <ti><brite><subslots></brite></ti> <ti> - This tag contains a description of the package. This is to augment the - DESCRIPTION field in the ebuilds themselves. This tag has two optional - subtags: <brite><pkg></brite> and <brite><cat></brite>. + Describes the meaning of subslots for the whole package. This + tag may appear at most once. </ti> </tr> <tr> @@ -113,25 +148,30 @@ A <path>metadata.xml</path> file can contain a number of tags: <ti><brite><upstream></brite></ti> <ti> This tag contains information about the upstream developers/project. + It supports multiple optional subtags: <maintainer>, + <changelog>, <doc>, <bugs-to>, + and <remote-id>. </ti> </tr> <tr> <ti><brite><maintainer></brite></ti> <ti> - Name and e-mail of an upstream maintainer. May appear more than once. + Provides information about the upstream maintainer. It requires a + <name> subtag to be specified, supports an optional + <email> subtag and an optional <c>status</c> attribute. </ti> </tr> <tr> - <ti><brite><email></brite></ti> + <ti><brite><name></brite></ti> <ti> - The email address of an upstream may appear only once and must appear in first place. + The name of an upstream maintainer should contain a block of text with upstream's name. + This element is mandatory for an upstream maintainer and must appear exactly once. </ti> </tr> <tr> - <ti><brite><name></brite></ti> + <ti><brite><email></brite></ti> <ti> - The name of an upstream maintainer should contain a block of text with upstream's name. - This element is mandatory for an upstream maintainer and must appear only once. + The email address of an upstream maintainer. May appear only once. </ti> </tr> <tr> @@ -141,7 +181,7 @@ A <path>metadata.xml</path> file can contain a number of tags: The URL must be version independent and must point to a changelog which is only updated on new releases of the corresponding package. (This also implies that one can link to an automatically updated changelog in case of vcs snapshots - only.) + only). May appear at most once. </ti> </tr> <tr> @@ -151,14 +191,14 @@ A <path>metadata.xml</path> file can contain a number of tags: found. The link must not point to any third party documentation and must be version independent. If the documentation is available in more than one language, a lang attribute can be used which follows the same rules as the one for - longdescription. + <longdescription>. </ti> </tr> <tr> <ti><brite><bugs-to></brite></ti> <ti> Should contain a place where bugs can be filed, a URL or an e-mail address prefixed - with mailto:. + with <c>mailto:</c>. May appear at most once. </ti> </tr> <tr> @@ -167,12 +207,14 @@ A <path>metadata.xml</path> file can contain a number of tags: Should specify a type of package identification tracker and the identification that corresponds to the package in question. remote-id should make it easier to index information such as its Freshmeat ID or its CPAN name. + It has a mandatory attribute <c>type</c> which identifies the type + of upstream source. </ti> </tr> <tr> <ti><brite><pkg></brite></ti> <ti> - This tag contains a valid package name in the format of a DEPEND. + This tag contains a valid qualified package name. </ti> </tr> <tr> @@ -198,6 +240,7 @@ There are also some attributes that can be used with these tags: <ti>lang</ti> <ti> <brite><description></brite>, <brite><longdescription></brite>, + <brite><slots></brite>, <brite><use></brite>, <brite><doc></brite> </ti> <ti> @@ -216,25 +259,29 @@ There are also some attributes that can be used with these tags: <brite><longdescription></brite>, <brite><flag></brite> </ti> <ti> - The restrict attribute allows one to restrict the application of certain - tags to certain versions of a package. When this attribute is used, a tag - without this attribute must also exist. That tag without the restrict - attribute will serve as the default. The format of the restrict attribute - is that of the DEPEND flag, except that "<" and - ">" need to be specified by "&lt;" and "&gt;". + The restrict attribute allows one to restrict the application of + certain tags to certain versions of a package. When this attribute + is used, other tags with or without the restrict attribute must be + present to cover all the versions of the package. A tag without + the restrict attribute serves as the default. The format of the + restrict attribute is that of a EAPI=0 package dependency + specification. Due to the limitations of XML, the "<" and + ">" need to be specified using "&lt;" and "&gt;". </ti> </tr> <tr> <ti>name</ti> <ti> - <brite><flag></brite> + <brite><flag></brite>, <brite><slot></brite> </ti> <ti> - This attribute is required on the <brite><flag></brite> tag. It - simply contains the USE flag. - <br /><br /> - For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> - Enables ACPI</flag></c> + When this attribute is required on the <flag> tag, it + simply contains the name of the USE flag. For the + <slot> tag, it specifies the + <uri link="::general-concepts/slotting#slot-names"> + slot name</uri> to which it applies. A slot name of <c>"*"</c> + allows for a single <slot> tag to match all the slots of a + package, in which case no other slot tags may be present. </ti> </tr> <tr> @@ -243,9 +290,12 @@ There are also some attributes that can be used with these tags: <brite><maintainer></brite> </ti> <ti> - The upstream maintainer element has a status attribute, which is one of active or inactive. - This attribute is not mandatory. The absence of it shall be interpreted as unknown. - Please note: This attribute is only allowed in the <upstream> <maintainer> element! + The upstream maintainer element has a status attribute, which is + one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not + mandatory. The absence of it shall be interpreted as + <c>"unknown"</c>. Please note that this attribute is only allowed + for the <maintainer> subtags of the <upstream> + element! </ti> </tr> <tr> @@ -446,9 +496,9 @@ project. Note the use of "&gt;" as opposed to ">" in <p> The example also uses the <c><pkg></c> tag in USE flag -descriptions. Slot operators are not allowed inside <pkg>, -therefore the notation <pkg>sys-boot/grub</pkg><c>:2</c> -is adopted as opposed to +descriptions. Slot dependency specifiers are not allowed inside +<pkg>, therefore the notation +<pkg>sys-boot/grub</pkg><c>:2</c> is adopted as opposed to <pkg>sys-boot/grub<c>:2</c></pkg>. </p> @@ -553,11 +603,7 @@ part of the QA reports. <body> <p> For categories, <c>metadata.xml</c> specifies a long description (in -English and optionally in other languages). The format is specified -formally in <uri link="https://wiki.gentoo.org/wiki/GLEP:34";> -GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified -by <uri link="https://wiki.gentoo.org/wiki/GLEP:31";>GLEP -31</uri>. A typical example: +English and optionally in other languages). A typical example: </p> <codesample lang="sgml"> -- 2.7.3
