<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title xmlns:d="http://docbook.org/ns/docbook">4.2. For upstream projects providing addons</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="publican v4.3.2" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="AppStream-AppStream-0.11-en-US-0.0-0" /><link rel="home" href="index.html" title="AppStream" /><link rel="up" href="chap-Quickstart.html" title="Chapter 4. Metadata Quickstart" /><link rel="prev" href="chap-Quickstart.html" title="Chapter 4. Metadata Quickstart" /><link rel="next" href="sect-Quickstart-Distros.html" title="4.3. For distributors packaging Appstream metadata" /></head><body><p id="title"><a class="left" href="http://www.freedesktop.org/wiki/Distributions/AppStream/"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="http://www.freedesktop.org/software/appstream/docs/"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="chap-Quickstart.html"><strong>Prev</strong></a></li><li class="home">AppStream</li><li class="next"><a accesskey="n" href="sect-Quickstart-Distros.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="section" lang="en-US"><div class="titlepage"><div><div><h2 class="title"><a id="sect-Quickstart-Addons">
</a>4.2. For upstream projects providing addons</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="qsr-addon-introduction">
</a>4.2.1. Introduction</h3></div></div></div><div class="para">
TODO: write short intro
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="qsr-addon-example">
</a>4.2.2. Example file</h3></div></div></div><div class="para">
The file should contain something like this:
</div><pre class="programlisting"><span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><?xml</span> version="1.0" encoding="UTF-8"<span xmlns="" class="perl_Keyword">?></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"><component</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"addon"</span><span xmlns="" class="perl_Keyword">></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><id></span>gedit-bookmarks<span xmlns="" class="perl_Keyword"></id></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><extends></span>gedit.desktop<span xmlns="" class="perl_Keyword"></extends></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><name></span>Bookmarks<span xmlns="" class="perl_Keyword"></name></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><summary></span>Easy document navigation with bookmarks<span xmlns="" class="perl_Keyword"></summary></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><url</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"homepage"</span><span xmlns="" class="perl_Keyword">></span>https://wiki.gnome.org/Apps/Gedit/ShippedPlugins<span xmlns="" class="perl_Keyword"></url></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><url</span><span xmlns="" class="perl_Others"> type=</span><span xmlns="" class="perl_String">"bugtracker"</span><span xmlns="" class="perl_Keyword">></span>https://bugzilla.gnome.org/enter_bug.cgi?product=gedit<span xmlns="" class="perl_DecVal">&amp;</span>component=Plugins<span xmlns="" class="perl_Keyword"></url></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><metadata_license></span>CC0-1.0<span xmlns="" class="perl_Keyword"></metadata_license></span>
<span xmlns="" class="line"></span> <span xmlns="" class="perl_Keyword"><project_license></span>GPL-2.0+<span xmlns="" class="perl_Keyword"></project_license></span>
<span xmlns="" class="line"></span><span xmlns="" class="perl_Keyword"></component></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="qsr-addon-content">
</a>4.2.3. Metadata file contents</h3></div></div></div><div class="para">
This is a list of tags you might want to define for your application. For a full list of possible tags, take a look at the definition of a generic component (<a class="xref" href="chap-Metadata.html#spec-component-filespec">Section 2.1.3, “XML Specification”</a>) and an addon component (<a class="xref" href="sect-Metadata-Addon.html#spec-addondata-filespec">Section 2.6.3, “File specification”</a>).
</div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><id/></span></dt><dd><div class="para">
For addons, there is no strict rule for the component-ID. You should just ensure that you pick a unique name.
</div><div class="para">
It is highly recommended to apply a <code class="code">application_name-plugin_name</code> naming scheme for your addon-id.
</div></dd><dt><span class="term"><extends/></span></dt><dd><div class="para">
This tag is refers to the ID of the component this addon is extending. For desktop applications, this is usually the name of their <code class="filename">.desktop</code> file.
</div><div class="para">
This tag is described in detail for addon components at <a class="xref" href="sect-Metadata-Addon.html#tag-extends"><extends/></a>.
</div></dd><dt><span class="term"><name/></span></dt><dd><div class="para">
Each addon component needs a <code class="literal"><name/></code> tag, giving the addon a human-readable name.
</div><div xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
Don't put the application name you are extending in the <code class="literal"><name/></code> - so you want to use <code class="code">Bookmarks</code> rather than <code class="code">GEdit Bookmarks</code>
</div></div></div></dd><dt><span class="term"><summary/></span></dt><dd><div class="para">
The <code class="literal"><summary/></code> tag follows the basic structure of a <a class="xref" href="chap-Metadata.html#tag-summary"><summary/></a> as described in the specification. It is a required tag for an addon component.
</div><div class="para">
Some useful hints for finding a good addon summary:
</div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
Don't put the application name you are extending in the <code class="literal"><summary/></code> - so you want to use <code class="code">Easy document navigation with bookmarks</code> rather than <code class="code">Easy document navigation with bookmarks in GEdit</code>.
</div></li><li class="listitem"><div class="para">
Don't use long or short descriptions. Ideally <code class="literal"><summmary/></code> should be less than <code class="code">101</code> and more than <code class="code">8</code>.
</div></li></ul></div></dd><dt><span class="term"><url/></span></dt><dd><div class="para">
It is recommended to include links of types <code class="code">homepage</code> and <code class="code">bugtracker</code>. You can omit the <code class="literal"><url/></code> if it's the same as the upstream project.
</div><div class="para">
Links of type <code class="code">homepage</code> should be a link to the upstream homepage for the addon.
</div><div class="para">
Links of type <code class="code">bugtracker</code> should be a link to the upstream bugtracker.
</div><div xmlns:d="http://docbook.org/ns/docbook" class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
It is highly recommended to be a link to the upstream bugzilla with filed component and product.
</div></div></div><div xmlns:d="http://docbook.org/ns/docbook" class="warning"><div class="admonition_header"><p><strong>Warning</strong></p></div><div class="admonition"><div class="para">
It might be necessary to escape URLs. For example replacing of <code class="code">&</code> with <code class="code">&amp;</code>.
</div></div></div><div class="para">
For other possible values, take a look at the tag's description in <a class="xref" href="chap-Metadata.html#tag-url"><url/></a>.
</div></dd><dt><span class="term"><metadata_license/></span></dt><dd><div class="para">
The <code class="code"><metadata_license/></code> tag is indicating the content license that you are releasing the one metadata file as. This is not typically the same as the project license. By ommitting the license value would probably mean your data would not be incorporated into the distribution metadata. Permissible license codes include:
</div><div class="para">
The license codes correspond to the identifiers found at the <a href="http://spdx.org/licenses/">SPDX OpenSource License Registry</a>. Take a look at <a class="xref" href="chap-Metadata.html#tag-metadata_license"><metadata_license/></a> for more details about this tag.
</div></dd><dt><span class="term"><project_license/></span></dt><dd><div class="para">
The <code class="literal"><project_license/></code> tag is indicating the license(s) this addon is released under. Take a look at the specification of the <a class="xref" href="chap-Metadata.html#tag-project_license"><project_license/></a> tag for details on how to properly use it.
</div></dd><dt><span class="term"><update_contact/></span></dt><dd><div class="para">
You might want to include an update-contact email address. Take a look at the specification of the <a class="xref" href="chap-Metadata.html#tag-update_contact"><update_contact/></a> tag for more details on how to use this tag.
</div></dd></dl></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Quickstart.html"><strong>Prev</strong>Chapter 4. Metadata Quickstart</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="sect-Quickstart-Distros.html"><strong>Next</strong>4.3. For distributors packaging Appstream metadata</a></li></ul></body></html>
