| 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 | 140 ++++++++++++++++++---------- |
| 11 |
1 file changed, 93 insertions(+), 47 deletions(-) |
| 12 |
|
| 13 |
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml |
| 14 |
index 31ec926..3d135a6 100644 |
| 15 |
--- a/ebuild-writing/misc-files/metadata/text.xml |
| 16 |
+++ b/ebuild-writing/misc-files/metadata/text.xml |
| 17 |
@@ -14,7 +14,15 @@ 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">GLEP 68</uri>. |
| 24 |
+The character set <b>must</b> be UTF-8 as specified by |
| 25 |
+<uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP 31</uri>. |
| 26 |
+</p> |
| 27 |
+ |
| 28 |
+<p> |
| 29 |
+The following table summarizes the tags that may appear in a |
| 30 |
+metadata.xml: |
| 31 |
</p> |
| 32 |
|
| 33 |
<table> |
| 34 |
@@ -24,28 +32,41 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 35 |
</tr> |
| 36 |
<tr> |
| 37 |
<ti> |
| 38 |
+ <brite><catmetadata></brite> |
| 39 |
+ </ti> |
| 40 |
+ <ti> |
| 41 |
+ This is the root element of the <path>metadata.xml</path> file for |
| 42 |
+ categories. It has no attributes. It contains a number of |
| 43 |
+ <brite><longdescription></brite> tags, each for a different |
| 44 |
+ language. |
| 45 |
+ </ti> |
| 46 |
+</tr> |
| 47 |
+<tr> |
| 48 |
+ <ti> |
| 49 |
<brite><pkgmetadata></brite> |
| 50 |
</ti> |
| 51 |
<ti> |
| 52 |
This is the root element of the <path>metadata.xml</path> file for |
| 53 |
packages. It has no attributes. The following subtags are |
| 54 |
allowed: |
| 55 |
- <brite><maintainer></brite>, |
| 56 |
<brite><longdescription></brite>, |
| 57 |
+ <brite><maintainer></brite>, |
| 58 |
+ <brite><slots></brite>, |
| 59 |
<brite><use></brite>, and |
| 60 |
<brite><upstream></brite>. |
| 61 |
+ While all the subtags are optional, <upstream> may |
| 62 |
+ appear at most once. |
| 63 |
</ti> |
| 64 |
</tr> |
| 65 |
<tr> |
| 66 |
+ <ti><brite><longdescription></brite></ti> |
| 67 |
<ti> |
| 68 |
- <brite><catmetadata></brite> |
| 69 |
- </ti> |
| 70 |
- <ti> |
| 71 |
- This is the root element of the <path>metadata.xml</path> file for |
| 72 |
- categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34">GLEP 34</uri>. |
| 73 |
- It has no attributes. It contains a number of |
| 74 |
- <brite><longdescription></brite> tags, each for a different |
| 75 |
- language. |
| 76 |
+ This tag contains a description for a category or a package. For |
| 77 |
+ packages, it is used to augment the |
| 78 |
+ <uri link="::ebuild-writing/variables#ebuild-defined-variables"> |
| 79 |
+ DESCRIPTION</uri> field in the ebuilds themselves. This tag has |
| 80 |
+ two optional subtags: <brite><pkg></brite> and |
| 81 |
+ <brite><cat></brite>. |
| 82 |
</ti> |
| 83 |
</tr> |
| 84 |
<tr> |
| 85 |
@@ -83,11 +104,25 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 86 |
</ti> |
| 87 |
</tr> |
| 88 |
<tr> |
| 89 |
- <ti><brite><longdescription></brite></ti> |
| 90 |
+ <ti><brite><slots></brite></ti> |
| 91 |
+ <ti> |
| 92 |
+ This tag describes the |
| 93 |
+ <uri link="::general-concepts/slotting">slots</uri> of a package. |
| 94 |
+ It has two optional subtags: <slot> and <subslots>. |
| 95 |
+ </ti> |
| 96 |
+</tr> |
| 97 |
+<tr> |
| 98 |
+ <ti><brite><slot></brite></ti> |
| 99 |
+ <ti> |
| 100 |
+ This contains information for a particular slot. The <c>name</c> |
| 101 |
+ attribute is mandatory and specifies the name of the slot. |
| 102 |
+ </ti> |
| 103 |
+</tr> |
| 104 |
+<tr> |
| 105 |
+ <ti><brite><subslots></brite></ti> |
| 106 |
<ti> |
| 107 |
- This tag contains a description of the package. This is to augment the |
| 108 |
- DESCRIPTION field in the ebuilds themselves. This tag has two optional |
| 109 |
- subtags: <brite><pkg></brite> and <brite><cat></brite>. |
| 110 |
+ Describes the meaning of subslots for the whole package. This |
| 111 |
+ tag may appear at most once. |
| 112 |
</ti> |
| 113 |
</tr> |
| 114 |
<tr> |
| 115 |
@@ -113,25 +148,30 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 116 |
<ti><brite><upstream></brite></ti> |
| 117 |
<ti> |
| 118 |
This tag contains information about the upstream developers/project. |
| 119 |
+ It supports multiple optional subtags: <maintainer>, |
| 120 |
+ <changelog>, <doc>, <bugs-to>, |
| 121 |
+ and <remote-id>. |
| 122 |
</ti> |
| 123 |
</tr> |
| 124 |
<tr> |
| 125 |
<ti><brite><maintainer></brite></ti> |
| 126 |
<ti> |
| 127 |
- Name and e-mail of an upstream maintainer. May appear more than once. |
| 128 |
+ Provides information about the upstream maintainer. It requires a |
| 129 |
+ <name> subtag to be specified, supports an optional |
| 130 |
+ <email> subtag and an optional <c>status</c> attribute. |
| 131 |
</ti> |
| 132 |
</tr> |
| 133 |
<tr> |
| 134 |
- <ti><brite><email></brite></ti> |
| 135 |
+ <ti><brite><name></brite></ti> |
| 136 |
<ti> |
| 137 |
- The email address of an upstream may appear only once and must appear in first place. |
| 138 |
+ The name of an upstream maintainer should contain a block of text with upstream's name. |
| 139 |
+ This element is mandatory for an upstream maintainer and must appear exactly once. |
| 140 |
</ti> |
| 141 |
</tr> |
| 142 |
<tr> |
| 143 |
- <ti><brite><name></brite></ti> |
| 144 |
+ <ti><brite><email></brite></ti> |
| 145 |
<ti> |
| 146 |
- The name of an upstream maintainer should contain a block of text with upstream's name. |
| 147 |
- This element is mandatory for an upstream maintainer and must appear only once. |
| 148 |
+ The email address of an upstream maintainer. May appear only once. |
| 149 |
</ti> |
| 150 |
</tr> |
| 151 |
<tr> |
| 152 |
@@ -141,7 +181,7 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 153 |
The URL must be version independent and must point to a changelog which is only |
| 154 |
updated on new releases of the corresponding package. (This also implies that |
| 155 |
one can link to an automatically updated changelog in case of vcs snapshots |
| 156 |
- only.) |
| 157 |
+ only). May appear at most once. |
| 158 |
</ti> |
| 159 |
</tr> |
| 160 |
<tr> |
| 161 |
@@ -151,14 +191,14 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 162 |
found. The link must not point to any third party documentation and must be |
| 163 |
version independent. If the documentation is available in more than one language, |
| 164 |
a lang attribute can be used which follows the same rules as the one for |
| 165 |
- longdescription. |
| 166 |
+ <longdescription>. |
| 167 |
</ti> |
| 168 |
</tr> |
| 169 |
<tr> |
| 170 |
<ti><brite><bugs-to></brite></ti> |
| 171 |
<ti> |
| 172 |
Should contain a place where bugs can be filed, a URL or an e-mail address prefixed |
| 173 |
- with mailto:. |
| 174 |
+ with <c>mailto:</c>. May appear at most once. |
| 175 |
</ti> |
| 176 |
</tr> |
| 177 |
<tr> |
| 178 |
@@ -167,12 +207,14 @@ A <path>metadata.xml</path> file can contain a number of tags: |
| 179 |
Should specify a type of package identification tracker and the identification that |
| 180 |
corresponds to the package in question. remote-id should make it easier to index |
| 181 |
information such as its Freshmeat ID or its CPAN name. |
| 182 |
+ It has a mandatory attribute <c>type</c> which identifies the type |
| 183 |
+ of upstream source. |
| 184 |
</ti> |
| 185 |
</tr> |
| 186 |
<tr> |
| 187 |
<ti><brite><pkg></brite></ti> |
| 188 |
<ti> |
| 189 |
- This tag contains a valid package name in the format of a DEPEND. |
| 190 |
+ This tag contains a valid qualified package name. |
| 191 |
</ti> |
| 192 |
</tr> |
| 193 |
<tr> |
| 194 |
@@ -198,6 +240,7 @@ There are also some attributes that can be used with these tags: |
| 195 |
<ti>lang</ti> |
| 196 |
<ti> |
| 197 |
<brite><description></brite>, <brite><longdescription></brite>, |
| 198 |
+ <brite><slots></brite>, |
| 199 |
<brite><use></brite>, <brite><doc></brite> |
| 200 |
</ti> |
| 201 |
<ti> |
| 202 |
@@ -216,25 +259,29 @@ There are also some attributes that can be used with these tags: |
| 203 |
<brite><longdescription></brite>, <brite><flag></brite> |
| 204 |
</ti> |
| 205 |
<ti> |
| 206 |
- The restrict attribute allows one to restrict the application of certain |
| 207 |
- tags to certain versions of a package. When this attribute is used, a tag |
| 208 |
- without this attribute must also exist. That tag without the restrict |
| 209 |
- attribute will serve as the default. The format of the restrict attribute |
| 210 |
- is that of the DEPEND flag, except that "<" and |
| 211 |
- ">" need to be specified by "&lt;" and "&gt;". |
| 212 |
+ The restrict attribute allows one to restrict the application of |
| 213 |
+ certain tags to certain versions of a package. When this attribute |
| 214 |
+ is used, other tags with or without the restrict attribute must be |
| 215 |
+ present to cover all the versions of the package. A tag without |
| 216 |
+ the restrict attribute serves as the default. The format of the |
| 217 |
+ restrict attribute is that of a EAPI=0 package dependency |
| 218 |
+ specification. Due to the limitations of XML, the "<" and |
| 219 |
+ ">" need to be specified using "&lt;" and "&gt;". |
| 220 |
</ti> |
| 221 |
</tr> |
| 222 |
<tr> |
| 223 |
<ti>name</ti> |
| 224 |
<ti> |
| 225 |
- <brite><flag></brite> |
| 226 |
+ <brite><flag></brite>, <brite><slot></brite> |
| 227 |
</ti> |
| 228 |
<ti> |
| 229 |
- This attribute is required on the <brite><flag></brite> tag. It |
| 230 |
- simply contains the USE flag. |
| 231 |
- <br /><br /> |
| 232 |
- For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> |
| 233 |
- Enables ACPI</flag></c> |
| 234 |
+ When this attribute is required on the <flag> tag, it |
| 235 |
+ simply contains the name of the USE flag. For the |
| 236 |
+ <slot> tag, it specifies the |
| 237 |
+ <uri link="::general-concepts/slotting#slot-names"> |
| 238 |
+ slot name</uri> to which it applies. A slot name of <c>"*"</c> |
| 239 |
+ allows for a single <slot> tag to match all the slots of a |
| 240 |
+ package, in which case no other slot tags may be present. |
| 241 |
</ti> |
| 242 |
</tr> |
| 243 |
<tr> |
| 244 |
@@ -243,9 +290,12 @@ There are also some attributes that can be used with these tags: |
| 245 |
<brite><maintainer></brite> |
| 246 |
</ti> |
| 247 |
<ti> |
| 248 |
- The upstream maintainer element has a status attribute, which is one of active or inactive. |
| 249 |
- This attribute is not mandatory. The absence of it shall be interpreted as unknown. |
| 250 |
- Please note: This attribute is only allowed in the <upstream> <maintainer> element! |
| 251 |
+ The upstream maintainer element has a status attribute, which is |
| 252 |
+ one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not |
| 253 |
+ mandatory. The absence of it shall be interpreted as |
| 254 |
+ <c>"unknown"</c>. Please note that this attribute is only allowed |
| 255 |
+ for the <maintainer> subtags of the <upstream> |
| 256 |
+ element! |
| 257 |
</ti> |
| 258 |
</tr> |
| 259 |
<tr> |
| 260 |
@@ -446,9 +496,9 @@ project. Note the use of "&gt;" as opposed to ">" in |
| 261 |
|
| 262 |
<p> |
| 263 |
The example also uses the <c><pkg></c> tag in USE flag |
| 264 |
-descriptions. Slot operators are not allowed inside <pkg>, |
| 265 |
-therefore the notation <pkg>sys-boot/grub</pkg><c>:2</c> |
| 266 |
-is adopted as opposed to |
| 267 |
+descriptions. Slot dependency specifiers are not allowed inside |
| 268 |
+<pkg>, therefore the notation |
| 269 |
+<pkg>sys-boot/grub</pkg><c>:2</c> is adopted as opposed to |
| 270 |
<pkg>sys-boot/grub<c>:2</c></pkg>. |
| 271 |
</p> |
| 272 |
|
| 273 |
@@ -553,11 +603,7 @@ part of the QA reports. |
| 274 |
<body> |
| 275 |
<p> |
| 276 |
For categories, <c>metadata.xml</c> specifies a long description (in |
| 277 |
-English and optionally in other languages). The format is specified |
| 278 |
-formally in <uri link="https://wiki.gentoo.org/wiki/GLEP:34"> |
| 279 |
-GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified |
| 280 |
-by <uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP |
| 281 |
-31</uri>. A typical example: |
| 282 |
+English and optionally in other languages). A typical example: |
| 283 |
</p> |
| 284 |
|
| 285 |
<codesample lang="sgml"> |
| 286 |
-- |
| 287 |
2.7.3 |
Archives