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 | 120 +++++++++++++++++++--------- 1 file changed, 83 insertions(+), 37 deletions(-) diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml index 1d26ede..12a9dc1 100644 --- a/ebuild-writing/misc-files/metadata/text.xml +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -14,7 +14,14 @@ 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>. +</p> + +<p> +The following table summarizes the tags that may appear in a +metadata.xml: </p> <table> @@ -24,28 +31,37 @@ 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>. </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 DESCRIPTION field in the + ebuilds themselves. This tag has two optional subtags: + <brite><pkg></brite> and <brite><cat></brite>. </ti> </tr> <tr> @@ -84,11 +100,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 optional 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 only once. </ti> </tr> <tr> @@ -114,25 +144,31 @@ 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 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. May appear + more than once. 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 only 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> @@ -159,7 +195,7 @@ A <path>metadata.xml</path> file can contain a number of tags: <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>. </ti> </tr> <tr> @@ -168,12 +204,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> @@ -199,6 +237,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> @@ -217,25 +256,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> @@ -244,9 +287,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> -- 2.7.3
