From: "Markos Chandras" <hwoarang@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/metadata/
Date: Sun, 11 Nov 2012 19:33:34 +0000 (UTC) [thread overview]
Message-ID: <1352662344.87754bded18b620fd926426acf0733b8f9a8403e.hwoarang@gentoo> (raw)
commit: 87754bded18b620fd926426acf0733b8f9a8403e
Author: Markos Chandras <hwoarang <AT> gentoo <DOT> org>
AuthorDate: Sat Nov 3 22:20:06 2012 +0000
Commit: Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Sun Nov 11 19:32:24 2012 +0000
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=87754bde
metadata: Add examples from the devrel handbook
---
ebuild-writing/misc-files/metadata/text.xml | 464 +++++++++++++++++++++++++--
1 files changed, 442 insertions(+), 22 deletions(-)
diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml
index 1cd4081..5e6cd52 100644
--- a/ebuild-writing/misc-files/metadata/text.xml
+++ b/ebuild-writing/misc-files/metadata/text.xml
@@ -19,31 +19,452 @@ provided, an English long description must be present. A typical
example might look like:
</p>
+<subsection>
+<body>
+
+<p>
+A <path>metadata.xml</path> file can contain a number of tags:
+</p>
+
+<table>
+<tr>
+ <th>tag</th>
+ <th>description</th>
+</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><herd></brite>,
+ <brite><maintainer></brite>,
+ <brite><longdescription></brite>,
+ <brite><use></brite>, and
+ <brite><upstream></brite>.
+ There should be at least one <brite><herd></brite> or
+ <brite><maintainer></brite> subtag.
+ </ti>
+</tr>
+<tr>
+ <ti>
+ <brite><catmetadata></brite>
+ </ti>
+ <ti>
+ This is the root element of the <path>metadata.xml</path> file for
+ categories as per <uri link="/proj/en/glep/glep-0034.html">GLEP 34</uri>.
+ It has no attributes. It contains a number of
+ <brite><longdescription></brite> tags, each for a different
+ language.
+ </ti>
+</tr>
+<tr>
+ <ti>
+ <brite><herd></brite>
+ </ti>
+ <ti>
+ If a package is maintained by one or more herds, names of these herds
+ can be specified with the <brite><herd></brite> tag. The names
+ used in this tag must be the same as specified in the <uri
+ link="http://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD">herds.xml</uri>
+ file.
+ </ti>
+</tr>
+<tr>
+ <ti>
+ <brite><maintainer></brite>
+ </ti>
+ <ti>
+ Besides being part of a herd, a package can also be maintained directly.
+ The maintainers of a package can be specified with the
+ <brite><maintainer></brite> tag. This tag has one required subtag:
+ <brite><email></brite>. It has two optional subtags:
+ <brite><name></brite>, and <brite><description></brite>.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><email></brite></ti>
+ <ti>
+ This contains the e-mail address of the maintainer. It is required.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><name></brite></ti>
+ <ti>
+ This contains freetext with the name of the maintainer. It is optional.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><description></brite></ti>
+ <ti>
+ The description tag contains a description of the maintainership, or for
+ example a remark that someone interested can take over the maintainership.
+ It is optional.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><longdescription></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>.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><use></brite></ti>
+ <ti>
+ This tag contains descriptions of <uri
+ link="::ebuild-writing/variables#iuse">USE flags</uri>.
+ This tag is optional and, if specified, has one required subtag:
+ <brite><flag></brite>.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><flag></brite></ti>
+ <ti>
+ This tag contains a description of how the named USE flag affects this
+ package. It is required if the <brite><use></brite> tag is specified.
+ It also requires the USE flag to be named in the <c>name</c> attribute.
+ This tag has two optional subtags: <brite><pkg></brite> and
+ <brite><cat></brite>.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><upstream></brite></ti>
+ <ti>
+ This tag contains information about the upstream developers/project.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><maintainer></brite></ti>
+ <ti>
+ Name and e-mail of an upstream maintainer. May appear more than once.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><name></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.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><email></brite></ti>
+ <ti>
+ The email address of an upstream may appear only once.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><changelog></brite></ti>
+ <ti>
+ Should contain a URL where the location of the upstream changelog can be found.
+ 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.)
+ </ti>
+</tr>
+<tr>
+ <ti><brite><doc></brite></ti>
+ <ti>
+ Should contain a URL where the location of the upstream documentation can be
+ 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.
+ </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:.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><remote-id></brite></ti>
+ <ti>
+ 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.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><pkg></brite></ti>
+ <ti>
+ This tag contains a valid package name in the format of a DEPEND.
+ </ti>
+</tr>
+<tr>
+ <ti><brite><cat></brite></ti>
+ <ti>
+ This tag contains a valid category name as defined in
+ <path>profiles/categories</path>.
+ </ti>
+</tr>
+</table>
+
+<p>
+There are also some attributes that can be used with these tags. They are all
+optional:
+</p>
+
+<table>
+<tr>
+ <th>attribute</th>
+ <th>tags</th>
+ <th>description</th>
+</tr>
+<tr>
+ <ti>lang</ti>
+ <ti>
+ <brite><description></brite>, <brite><longdescription></brite>,
+ <brite><use></brite>, <brite><doc></brite>
+ </ti>
+ <ti>
+ In every case where a description is required, there must be at
+ <e>least</e> an english description. If an additional description in
+ another language is given, this attribute is used to specify the language
+ used. The format is the two-character language code as defined by the <uri
+ link="http://www.w3.org/WAI/ER/IG/ert/iso639.htm#2letter">ISO-639-1</uri>
+ norm.
+ </ti>
+</tr>
+<tr>
+ <ti>restrict</ti>
+ <ti>
+ <brite><herd></brite>, <brite><maintainer></brite>,
+ <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;.<br />
+ <br />
+ For example, in the <c>sys-libs/db</c> package,
+ <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the
+ <brite>maintainer</brite> tag shows that I'm currently maintaining all
+ versions greater then 3.2.9-r5.
+ </ti>
+</tr>
+<tr>
+ <ti>name</ti>
+ <ti>
+ <brite><flag></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>
+ </ti>
+</tr>
+<tr>
+ <ti>status</ti>
+ <ti>
+ <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!
+ </ti>
+</tr>
+<tr>
+ <ti>type</ti>
+ <ti>
+ <brite><remote-id></brite>
+ </ti>
+ <ti>
+ A string identifying the type of upstream source. A list of valid strings are kept in metadata.dtd.
+ Developers should email the gentoo-dev mailing list before using a new type value.
+ </ti>
+</tr>
+
+</table>
+
+</body>
+</subsection>
+
+</body>
+</section>
+
+<section>
+<title>Metadata Examples</title>
+<subsection>
+<title>First Example</title>
+<body>
+
+<p>
+In this first example we provide you with the <path>metadata.xml</path> for
+OpenOffice of which the ebuilds are completely managed by a herd called
+<c>openoffice</c>:
+</p>
+
<codesample lang="sgml">
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
- <pkgmetadata>
- <herd>freedesktop</herd>
- <maintainer>
- <email>dang@gentoo.org</email>
- <name>Daniel Gryniewicz</name>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <herd>openoffice</herd>
+ <longdescription>
+ OpenOffice is the opensource version of staroffice.
+ This ebuild allows you to compile it yourself. Unfortunately this
+ compilation can take up to a day depending on the speed of your
+ computer. It will however make a snappier openoffice than the binary
+ version.
+ </longdescription>
+</pkgmetadata>
+</codesample>
+
+<p>
+The <c>openoffice</c> herd is defined in <path>herds.xml</path> by the
+<uri link="/proj/en/metastructure">Gentoo Metastructure Project</uri>:
+</p>
+
+<note>
+This example may be outdated when you read it. It's just an example!
+</note>
+
+<codesample lang="sgml">
+<herd>
+ <name>openoffice</name>
+ <email>openoffice@gentoo.org</email>
+ <description>Openoffice related packages</description>
+ <maintainer><email>pauldv@gentoo.org</email></maintainer>
+ <maintainer><email>suka@gentoo.org</email></maintainer>
+</herd>
+</codesample>
+
+<p>
+If you want to add (or remove) yourself from a herd, edit <path>herds.xml</path>
+located in <path>[gentoo]/xml/htdocs/proj/en/metastructure/herds</path> in Gentoo's CVS repository. Make sure you
+know the e-mail alias the herd listens to (for instance the "sound" herd has
+<mail link="sound@gentoo.org">sound@gentoo.org</mail>) and add yourself to the
+alias (by editing <path>/var/mail/alias/misc/<alias name></path> on
+dev.gentoo.org).
+</p>
+
+</body>
+</subsection>
+<subsection>
+<title>Second Example</title>
+<body>
+
+<p>
+For the second example, we will examine the <path>metadata.xml</path> of
+<c>app-portage/mirrorselect</c>. This ebuild is maintained by the
+<c>tools-portage</c> herd, but has a separate maintainer.
+</p>
+
+<pre caption="Herd & individually maintained package">
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+ <herd>tools-portage</herd>
+ <maintainer>
+ <email>johnm@gentoo.org</email>
+ <name>John Mylchreest</name>
+ </maintainer>
+ <longdescription>
+ This utility is used to select the fastest mirror (distfiles) and provide a
+ nicer front-end for mirror selection (both rsync + distfiles) to a user.
+ </longdescription>
+</pkgmetadata>
+</pre>
+
+</body>
+</subsection>
+<subsection>
+<title>Third Example</title>
+<body>
+
+<p>
+For the third example, we will describe the <path>metadata.xml</path> of
+<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd
+and contains USE flag descriptions.
+</p>
+
+<codesample lang="sgml">
+<?xml version="1.0" encoding="UTF-8">
+<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
+<pkgmetadata>
+<herd>gentopia</herd>
+<maintainer>
+ <email>compnerd@gentoo.org</email>
+</maintainer>
+<maintainer>
+ <email>steev@gentoo.org</email>
+</maintainer>
+<use>
+ <flag name='acpi'>Enables HAL to attempt to read from
+ /proc/acpi/event, if unavailable, HAL will read events from
+ <pkg>sys-power/acpid</pkg>. If you need multiple acpi
+ readers, ensure acpid is in your default runlevel along with HAL. This
+ will also enable HAL to read Toshia and IBM acpi events which do not
+ get sent via /proc/acpi/event</flag>
+ <flag name='crypt'>Allows HAL to mount volumes that are encrypted using
+ LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed
+ to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted
+ volumes. HAL will be able to handle volumes that are removable or
+ fixed.</flag>
+ <flag name='dell'>Builds an installs the Dell addon, which reads data from
+ the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your
+ service tag information and your hardware backlight data as well as
+ allow you to modify the backlight settings on a Dell laptop.</flag>
+ <flag name='disk-partition'>Allows HAL to use libparted from
+ <pkg>sys-apps/parted</pkg> to read raw partition data from your disks
+ and process that data. Future versions of HAL (possibly 0.5.11 and
+ higher) will allow you to create, modify, delete and format partitions
+ from a GUI interface agnostic of your desktop environment.</flag>
+ <flag name='doc'>Generates documentation that describes HAL's fdi
+ format.</flag>
+ <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which
+ includes inserts and removals and act on these events.</flag>
+ <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux
+ libraries.</flag>
+</use>
+</pkgmetadata>
+</codesample>
+
+</body>
+</subsection>
+<subsection>
+<title>Fourth Example</title>
+<body>
+
+<p>
+This example demonstrates the usage of the upstream element:
+</p>
+
+<codesample lang="sgml">
+<upstream>
+ <maintainer status="inactive">
+ <name>Foo Bar</name>
+ <email>foo@bar.bar</email>
+ </maintainer>
+ <maintainer status="active">
+ <name>Foo Gentoo</name>
+ <email>foo@gentoo.org</email>
</maintainer>
- <longdescription lang="en">
- HAL provides a view of the various hardware attached to a system.
- In addition to this, HAL keeps detailed metadata for each piece of
- hardware and provide hooks such that system- and desktop-level software
- can react to changes in the hardware configuration in order to maintain
- system policy.
- </longdescription>
- <use>
- <flag name="laptop">Adds support for power management scripts
- (<pkg>sys-power/pm-utils</pkg>)</flag>
- <flag name="selinux">Installs SELinux policies and links HAL to the SELinux
- libraries.</flag>
- </use>
- </pkgmetadata>
+ <changelog>http://foo.bar/changelog.txt</changelog>
+ <doc lang="en">http://foo.bar/doc/index.html</doc>
+ <doc lang="de">http://foo.bar/doc/index.de.html</doc>
+ <bugs-to>https://bugs.foo.bar</bugs-to>
+ <remote-id type="freshmeat">foobar</remote-id>
+ <remote-id type="sourceforge">foobar</remote-id>
+</upstream>
</codesample>
+</body>
+</subsection>
+
+
<p>
All new packages <b>must</b> include a <c>metadata.xml</c> file. That file
should specify at least one herd or one maintainer. It is however recommended,
@@ -67,7 +488,6 @@ should ensure that you have <c>dev-libs/libxml2</c> installed so that
the XML can be validated.
</p>
-</body>
</section>
<section>
next reply other threads:[~2012-11-11 19:34 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-11-11 19:33 Markos Chandras [this message]
-- strict thread matches above, loose matches on Subject: below --
2022-06-01 20:39 [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/metadata/ Ulrich Müller
2022-05-27 9:04 Ulrich Müller
2022-01-12 6:34 Ulrich Müller
2022-01-12 6:34 Ulrich Müller
2022-01-12 6:34 Ulrich Müller
2021-09-11 21:59 Ulrich Müller
2020-04-20 8:02 Ulrich Müller
2020-04-20 8:02 Ulrich Müller
2020-04-20 8:02 Ulrich Müller
2020-01-23 7:47 Ulrich Müller
2020-01-14 20:36 Göktürk Yüksek
2017-04-13 19:35 Göktürk Yüksek
2016-12-11 6:19 Göktürk Yüksek
2016-05-18 5:32 Göktürk Yüksek
2016-05-18 5:32 Göktürk Yüksek
2016-05-18 5:32 Göktürk Yüksek
2016-05-18 5:32 Göktürk Yüksek
2016-05-18 5:32 Göktürk Yüksek
2016-02-05 12:59 Ulrich Müller
2016-02-05 12:59 Ulrich Müller
2014-01-19 15:14 Markos Chandras
2014-01-03 18:32 Markos Chandras
2013-05-12 15:06 Markos Chandras
2012-11-02 17:49 Markos Chandras
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=1352662344.87754bded18b620fd926426acf0733b8f9a8403e.hwoarang@gentoo \
--to=hwoarang@gentoo.org \
--cc=gentoo-commits@lists.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