From: "Göktürk Yüksek" <gokturk@binghamton.edu>
To: devmanual@gentoo.org
Cc: gentoo-dev@lists.gentoo.org
Subject: [gentoo-dev] [PATCH v1 3/5] ebuild-writing/misc-files/metadata: update wrt slotting and per GLEP 68
Date: Mon, 2 May 2016 06:16:43 -0400 [thread overview]
Message-ID: <1462184205-5644-4-git-send-email-gokturk@binghamton.edu> (raw)
In-Reply-To: <1462184205-5644-1-git-send-email-gokturk@binghamton.edu>
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 <gokturk@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
next prev parent reply other threads:[~2016-05-02 10:20 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-05-02 10:16 [gentoo-dev] [PATCH v1 0/5] devmanual: update the docs per GLEP 67 and 68 Göktürk Yüksek
2016-05-02 10:16 ` [gentoo-dev] [PATCH v1 1/5] general-concepts/herds-and-projects: update per GLEP 67 #572144 #549490 Göktürk Yüksek
2016-05-02 10:16 ` [gentoo-dev] [PATCH v1 2/5] ebuild-writing/misc-files/metadata: rewrite the section per GLEP 67 #572144 Göktürk Yüksek
2016-05-02 10:16 ` Göktürk Yüksek [this message]
2016-05-02 10:16 ` [gentoo-dev] [PATCH v1 4/5] ebuild-writing/misc-files/metadata: move the GLEP 31 reference to the top Göktürk Yüksek
2016-05-08 7:39 ` [gentoo-dev] " Ulrich Mueller
2016-05-08 15:30 ` Göktürk Yüksek
2016-05-02 10:16 ` [gentoo-dev] [PATCH v1 5/5] ebuild-writing/misc-files/metadata: add an example for slots and subslots Göktürk Yüksek
2016-05-08 7:48 ` [gentoo-dev] " Ulrich Mueller
2016-05-08 15:29 ` Göktürk Yüksek
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1462184205-5644-4-git-send-email-gokturk@binghamton.edu \
--to=gokturk@binghamton.edu \
--cc=devmanual@gentoo.org \
--cc=gentoo-dev@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox