| 1 |
Add information about specifying slots and subslots in the |
| 2 |
metadata. |
| 3 |
|
| 4 |
Also, update the section according to the specifications in GLEP 68, |
| 5 |
clarify some of the tags better, and reorder the tags to improve the |
| 6 |
flow of the text. |
| 7 |
|
| 8 |
Signed-off-by: Göktürk Yüksek <gokturk@××××××××××.edu> |
| 9 |
--- |
| 10 |
ebuild-writing/misc-files/metadata/text.xml | 120 +++++++++++++++++++--------- |
| 11 |
1 file changed, 83 insertions(+), 37 deletions(-) |
| 12 |
|
| 13 |
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml |
| 14 |
index 1d26ede..12a9dc1 100644 |
| 15 |
--- a/ebuild-writing/misc-files/metadata/text.xml |
| 16 |
+++ b/ebuild-writing/misc-files/metadata/text.xml |
| 17 |
@@ -14,7 +14,14 @@ package or category. |
| 18 |
<body> |
| 19 |
|
| 20 |
<p> |
| 21 |
-A <path>metadata.xml</path> file can contain a number of tags: |
| 22 |
+A metadata file follows the syntax defined in |
| 23 |
+<uri link="https://wiki.gentoo.org/wiki/GLEP:68"> |
| 24 |
+GLEP 68</uri>. |
| 25 |
+</p> |
| 26 |
+ |
| 27 |
+<p> |
| 28 |
+The following table summarizes the tags that may appear in a |
| 29 |
+metadata.xml: |
| 30 |
</p> |
| 31 |
|
| 32 |
<table> |
| 33 |
@@ -24,28 +31,37 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 34 |
</tr> |
| 35 |
<tr> |
| 36 |
<ti> |
| 37 |
+ <brite><catmetadata></brite> |
| 38 |
+ </ti> |
| 39 |
+ <ti> |
| 40 |
+ This is the root element of the <path>metadata.xml</path> file for |
| 41 |
+ categories. It has no attributes. It contains a number of |
| 42 |
+ <brite><longdescription></brite> tags, each for a different |
| 43 |
+ language. |
| 44 |
+ </ti> |
| 45 |
+</tr> |
| 46 |
+<tr> |
| 47 |
+ <ti> |
| 48 |
<brite><pkgmetadata></brite> |
| 49 |
</ti> |
| 50 |
<ti> |
| 51 |
This is the root element of the <path>metadata.xml</path> file for |
| 52 |
packages. It has no attributes. The following subtags are |
| 53 |
allowed: |
| 54 |
- <brite><maintainer></brite>, |
| 55 |
<brite><longdescription></brite>, |
| 56 |
+ <brite><maintainer></brite>, |
| 57 |
+ <brite><slots></brite>, |
| 58 |
<brite><use></brite>, and |
| 59 |
<brite><upstream></brite>. |
| 60 |
</ti> |
| 61 |
</tr> |
| 62 |
<tr> |
| 63 |
+ <ti><brite><longdescription></brite></ti> |
| 64 |
<ti> |
| 65 |
- <brite><catmetadata></brite> |
| 66 |
- </ti> |
| 67 |
- <ti> |
| 68 |
- This is the root element of the <path>metadata.xml</path> file for |
| 69 |
- categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34">GLEP 34</uri>. |
| 70 |
- It has no attributes. It contains a number of |
| 71 |
- <brite><longdescription></brite> tags, each for a different |
| 72 |
- language. |
| 73 |
+ This tag contains a description for a category or a package. For |
| 74 |
+ packages, it is used to augment the DESCRIPTION field in the |
| 75 |
+ ebuilds themselves. This tag has two optional subtags: |
| 76 |
+ <brite><pkg></brite> and <brite><cat></brite>. |
| 77 |
</ti> |
| 78 |
</tr> |
| 79 |
<tr> |
| 80 |
@@ -84,11 +100,25 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 81 |
</ti> |
| 82 |
</tr> |
| 83 |
<tr> |
| 84 |
- <ti><brite><longdescription></brite></ti> |
| 85 |
+ <ti><brite><slots></brite></ti> |
| 86 |
+ <ti> |
| 87 |
+ This optional tag describes the |
| 88 |
+ <uri link="::general-concepts/slotting">slots</uri> of a package. |
| 89 |
+ It has two optional subtags: <slot> and <subslots>. |
| 90 |
+ </ti> |
| 91 |
+</tr> |
| 92 |
+<tr> |
| 93 |
+ <ti><brite><slot></brite></ti> |
| 94 |
+ <ti> |
| 95 |
+ This contains information for a particular slot. The <c>name</c> |
| 96 |
+ attribute is mandatory and specifies the name of the slot. |
| 97 |
+ </ti> |
| 98 |
+</tr> |
| 99 |
+<tr> |
| 100 |
+ <ti><brite><subslots></brite></ti> |
| 101 |
<ti> |
| 102 |
- This tag contains a description of the package. This is to augment the |
| 103 |
- DESCRIPTION field in the ebuilds themselves. This tag has two optional |
| 104 |
- subtags: <brite><pkg></brite> and <brite><cat></brite>. |
| 105 |
+ Describes the meaning of subslots for the whole package. This |
| 106 |
+ tag may appear only once. |
| 107 |
</ti> |
| 108 |
</tr> |
| 109 |
<tr> |
| 110 |
@@ -114,25 +144,31 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 111 |
<ti><brite><upstream></brite></ti> |
| 112 |
<ti> |
| 113 |
This tag contains information about the upstream developers/project. |
| 114 |
+ It supports multiple subtags: <maintainer>, |
| 115 |
+ <changelog>, <doc>, <bugs-to>, |
| 116 |
+ and <remote-id>. |
| 117 |
</ti> |
| 118 |
</tr> |
| 119 |
<tr> |
| 120 |
<ti><brite><maintainer></brite></ti> |
| 121 |
<ti> |
| 122 |
- Name and e-mail of an upstream maintainer. May appear more than once. |
| 123 |
+ Provides information about the upstream maintainer. May appear |
| 124 |
+ more than once. It requires a <name> subtag to be |
| 125 |
+ specified, supports an optional <email> subtag and |
| 126 |
+ an optional <c>status</c> attribute. |
| 127 |
</ti> |
| 128 |
</tr> |
| 129 |
<tr> |
| 130 |
- <ti><brite><email></brite></ti> |
| 131 |
+ <ti><brite><name></brite></ti> |
| 132 |
<ti> |
| 133 |
- The email address of an upstream may appear only once and must appear in first place. |
| 134 |
+ The name of an upstream maintainer should contain a block of text with upstream's name. |
| 135 |
+ This element is mandatory for an upstream maintainer and must appear only once. |
| 136 |
</ti> |
| 137 |
</tr> |
| 138 |
<tr> |
| 139 |
- <ti><brite><name></brite></ti> |
| 140 |
+ <ti><brite><email></brite></ti> |
| 141 |
<ti> |
| 142 |
- The name of an upstream maintainer should contain a block of text with upstream's name. |
| 143 |
- This element is mandatory for an upstream maintainer and must appear only once. |
| 144 |
+ The email address of an upstream maintainer. May appear only once. |
| 145 |
</ti> |
| 146 |
</tr> |
| 147 |
<tr> |
| 148 |
@@ -159,7 +195,7 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 149 |
<ti><brite><bugs-to></brite></ti> |
| 150 |
<ti> |
| 151 |
Should contain a place where bugs can be filed, a URL or an e-mail address prefixed |
| 152 |
- with mailto:. |
| 153 |
+ with <c>mailto:</c>. |
| 154 |
</ti> |
| 155 |
</tr> |
| 156 |
<tr> |
| 157 |
@@ -168,12 +204,14 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 158 |
Should specify a type of package identification tracker and the identification that |
| 159 |
corresponds to the package in question. remote-id should make it easier to index |
| 160 |
information such as its Freshmeat ID or its CPAN name. |
| 161 |
+ It has a mandatory attribute <c>type</c> which identifies the type |
| 162 |
+ of upstream source. |
| 163 |
</ti> |
| 164 |
</tr> |
| 165 |
<tr> |
| 166 |
<ti><brite><pkg></brite></ti> |
| 167 |
<ti> |
| 168 |
- This tag contains a valid package name in the format of a DEPEND. |
| 169 |
+ This tag contains a valid qualified package name. |
| 170 |
</ti> |
| 171 |
</tr> |
| 172 |
<tr> |
| 173 |
@@ -199,6 +237,7 @@ There are also some attributes that can be used with these tags: |
| 174 |
<ti>lang</ti> |
| 175 |
<ti> |
| 176 |
<brite><description></brite>, <brite><longdescription></brite>, |
| 177 |
+ <brite><slots></brite>, |
| 178 |
<brite><use></brite>, <brite><doc></brite> |
| 179 |
</ti> |
| 180 |
<ti> |
| 181 |
@@ -217,25 +256,29 @@ There are also some attributes that can be used with these tags: |
| 182 |
<brite><longdescription></brite>, <brite><flag></brite> |
| 183 |
</ti> |
| 184 |
<ti> |
| 185 |
- The restrict attribute allows one to restrict the application of certain |
| 186 |
- tags to certain versions of a package. When this attribute is used, a tag |
| 187 |
- without this attribute must also exist. That tag without the restrict |
| 188 |
- attribute will serve as the default. The format of the restrict attribute |
| 189 |
- is that of the DEPEND flag, except that "<" and |
| 190 |
- ">" need to be specified by "&lt;" and "&gt;". |
| 191 |
+ The restrict attribute allows one to restrict the application of |
| 192 |
+ certain tags to certain versions of a package. When this attribute |
| 193 |
+ is used, other tags with or without the restrict attribute must be |
| 194 |
+ present to cover all the versions of the package. A tag without |
| 195 |
+ the restrict attribute serves as the default. The format of the |
| 196 |
+ restrict attribute is that of a EAPI=0 package dependency |
| 197 |
+ specification. Due to the limitations of XML, the "<" and |
| 198 |
+ ">" need to be specified using "&lt;" and "&gt;". |
| 199 |
</ti> |
| 200 |
</tr> |
| 201 |
<tr> |
| 202 |
<ti>name</ti> |
| 203 |
<ti> |
| 204 |
- <brite><flag></brite> |
| 205 |
+ <brite><flag></brite>, <brite><slot></brite> |
| 206 |
</ti> |
| 207 |
<ti> |
| 208 |
- This attribute is required on the <brite><flag></brite> tag. It |
| 209 |
- simply contains the USE flag. |
| 210 |
- <br /><br /> |
| 211 |
- For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> |
| 212 |
- Enables ACPI</flag></c> |
| 213 |
+ When this attribute is required on the <flag> tag, it |
| 214 |
+ simply contains the name of the USE flag. For the |
| 215 |
+ <slot> tag, it specifies the |
| 216 |
+ <uri link="::general-concepts/slotting#slot-names"> |
| 217 |
+ slot name</uri> to which it applies. A slot name of <c>"*"</c> |
| 218 |
+ allows for a single <slot> tag to match all the slots of a |
| 219 |
+ package, in which case no other slot tags may be present. |
| 220 |
</ti> |
| 221 |
</tr> |
| 222 |
<tr> |
| 223 |
@@ -244,9 +287,12 @@ There are also some attributes that can be used with these tags: |
| 224 |
<brite><maintainer></brite> |
| 225 |
</ti> |
| 226 |
<ti> |
| 227 |
- The upstream maintainer element has a status attribute, which is one of active or inactive. |
| 228 |
- This attribute is not mandatory. The absence of it shall be interpreted as unknown. |
| 229 |
- Please note: This attribute is only allowed in the <upstream> <maintainer> element! |
| 230 |
+ The upstream maintainer element has a status attribute, which is |
| 231 |
+ one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not |
| 232 |
+ mandatory. The absence of it shall be interpreted as |
| 233 |
+ <c>"unknown"</c>. Please note that this attribute is only allowed |
| 234 |
+ for the <maintainer> subtags of the <upstream> |
| 235 |
+ element! |
| 236 |
</ti> |
| 237 |
</tr> |
| 238 |
<tr> |
| 239 |
-- |
| 240 |
2.7.3 |
Archives