/usr/share/doc/appstream/html/sect-Metadata-Application.html is in appstream-doc 0.10.6-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | <?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">2.2. Desktop Applications</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.10-en-US-0.0-0" /><link rel="home" href="index.html" title="AppStream" /><link rel="up" href="chap-Metadata.html" title="Chapter 2. Upstream Metadata" /><link rel="prev" href="chap-Metadata.html" title="Chapter 2. Upstream Metadata" /><link rel="next" href="sect-Metadata-ConsoleApplication.html" title="2.3. Console Applications" /></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-Metadata.html"><strong>Prev</strong></a></li><li class="home">AppStream</li><li class="next"><a accesskey="n" href="sect-Metadata-ConsoleApplication.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-Metadata-Application">
</a>2.2. Desktop Applications</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="spec-appdata-introduction">
</a>2.2.1. Introduction</h3></div></div></div><div class="para">
A desktop application is an application which has a graphical user interface and is commonly used with mouse and keyboard. It also ships a Freedesktop <code class="filename">.desktop</code> file to be visible in application menus.
</div><div class="para">
AppStream generators may pull data from the preexisting <code class="filename">.desktop</code> files to represent an application in the AppStream metadata pool. Upstream projects should ship a small XML file containing additional metadata to describe their application though, to enhance the available metadata. This data includes things like screenshots, long descriptions, icon information and various other things needed to present the application properly to the user. For some distributions, the presence of this metadata is a prerequisite for the application showing up in the metadata pool and being presented in software centers.
</div><div class="para">
The file described in this document is built upon the generic component metadata with fields specific for desktop applications (see <a class="xref" href="chap-Metadata.html#sect-Metadata-GenericComponent">Section 2.1, “Generic Component”</a>).
</div><div class="para">
The metainfo files override any values which are automatically fetched from other sources by the AppStream data generator, which means that its data will always take precedence over data which has already been defined in a <code class="filename">.desktop</code> file. Applications can ship one or more files in <code class="filename">/usr/share/metainfo/%{id}.appdata.xml</code>.
</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">
If you are looking for some quickstart guide to just get your application to ship AppStream metadata quickly, this document might not be for you. You might want to take a look at <a class="xref" href="chap-Quickstart.html#sect-Quickstart-DesktopApps">Section 4.1, “For GUI application upstream maintainers”</a> instead.
</div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="spec-appdata-filespec">
</a>2.2.2. File specification</h3></div></div></div><div class="para">
The basic structure for a generic component as described at <a class="xref" href="chap-Metadata.html#spec-component-filespec">Section 2.1.3, “XML Specification”</a> applies. Note that the XML root must have the <code class="literal">type</code> property set to <code class="code">desktop-application</code>, while in a generic component this property can be omitted. This clearly identifies this metainfo document as describing an application.
</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">
All tags defined in the <code class="literal">generic</code> component specification are valid for <code class="literal">desktop-application</code> components as well. An application is just a specialized component, allowing tools like software centers to filter out the component types they want to display.
</div></div></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">
The <code class="code">desktop-application</code> component type is the same as the <code class="code">desktop</code> component type - <code class="code">desktop</code> is the older type identifier for desktop-applications and should not be used for new metainfo files, unless compatibility with very old AppStream tools (pre 2016) is still wanted.
</div></div></div><div class="para">
The following list describes the special tags for application upstream metadata and provides some additional information about the values the tags are expected to have. If no information is given about a tag, refer to the respective tag in <a class="xref" href="chap-Metadata.html#sect-Metadata-GenericComponent">Section 2.1, “Generic Component”</a>.
</div><div class="variablelist"><dl class="variablelist"><dt><a id="tag-id-desktopapp">
</a><span class="term"><id/></span></dt><dd><div class="para">
For applications, the <code class="code"><id/></code> tag value must be the same name as the installed <code class="filename">.desktop</code> file for the application, the <code class="filename">.desktop</code> suffix of the filename may be omitted.
</div><div class="para">
Usually, modern <code class="filename">.desktop</code> files follow the reverse-DNS scheme name already. If they do not follow the scheme, it is strongly recommended to change the <code class="filename">.desktop</code> filename. Refer to <a href="https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s02.html">the desktop entry specification</a> for more information.
</div><div class="para">
Example: If your application's <code class="filename">.desktop</code> file is named <code class="filename">org.example.FooBar.desktop</code> the component-id must be <code class="code">org.example.FooBar</code> (or <code class="code">org.example.FooBar.desktop</code>). If your application's <code class="filename">.desktop</code> file is named <code class="filename">frobnicator.desktop</code> the component-id must be <code class="code">frobnicator</code> (or <code class="code">frobnicator.desktop</code>) - it is highly recommended to modernize the .desktop filename to follow the Desktop Entry specification in these cases though.
</div></dd><dt><span class="term"><metadata_license/></span></dt><dd><div class="para">
The <code class="code"><metadata_license/></code> tag as described in <a class="xref" href="chap-Metadata.html#tag-metadata_license"><metadata_license/></a> must be present.
</div></dd><dt><a id="tag-dapp-name">
</a><span class="term"><name/></span></dt><dd><div class="para">
The human-readable name of the application. This is the name you want users to see prior to installing the application.
</div></dd><dt><a id="tag-dapp-summary">
</a><span class="term"><summary/></span></dt><dd><div class="para">
A short summary on what this application does, roughly equivalent to the <code class="literal">Comment</code> field of the accompanying <code class="filename">.desktop</code> file of the application.
</div></dd><dt><a id="tag-dapp-screenshots">
</a><span class="term"><screenshots/></span></dt><dd><div class="para">
A screenshot presents your application to the outside world, and could be seen by hundreds or thousands of people.
</div><div class="para">
The <code class="code"><screenshots/></code> tag should look like it is described at <a class="xref" href="chap-Metadata.html#tag-screenshots"><screenshots/></a>.
</div><div class="para">
Screenshot size, shape and format recommendations for applications:
</div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para">
All screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620px (software center applications will be able to fill in the screenshots in the space they provide for that more easily then).
</div><div class="para">
Ideally the window will be resized to a 16:9 aspect ratio, but screenshots can also be cropped if only a small area of the window needs to be shown.
</div></li><li class="listitem"><div class="para">
Screenshots should be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other images where a lossy format like JPEG may compress better.
</div></li><li class="listitem"><div class="para">
Do not scale screenshots below their original size.
</div></li></ul></div><div class="para">
You can find a lot more information on how to create good screenshots in the <a class="link" href="chap-Quickstart.html#qsr-app-screenshots-info">quickstart guide on applications</a>.
</div></dd><dt><span class="term"><project_group/></span></dt><dd><div class="para">
This tag is described for generic components at <a class="xref" href="chap-Metadata.html#spec-component-filespec">Section 2.1.3, “XML Specification”</a>. You should use it for your application if appropriate.
</div></dd><dt><span class="term"><provides/></span></dt><dd><div class="para">
This tag is described in detail for generic components at <a class="xref" href="chap-Metadata.html#tag-provides"><provides/></a>.
</div><div class="para">
If your application ships a binary in a location in the default <code class="envar">PATH</code>, you should add at least a child of type <code class="code"><binary/></code> to make that new executable known to the distribution.
</div></dd><dt><span class="term"><releases/></span></dt><dd><div class="para">
The application metainfo should at least provide one <code class="code"><releases/></code> tag, which has one or more <code class="code"><release/></code> childs to define the version and release date of this application. For details, see <a class="xref" href="chap-Metadata.html#tag-releases"><releases/></a> .
</div></dd></dl></div><div class="para">
For a component of type <code class="literal">desktop-application</code>, the following tags are required and must always be present: <a class="xref" href="sect-Metadata-Application.html#tag-id-desktopapp"><id/></a>, <a class="xref" href="sect-Metadata-Application.html#tag-dapp-name"><name/></a>, <a class="xref" href="sect-Metadata-Application.html#tag-dapp-summary"><summary/></a>, <a class="xref" href="chap-Metadata.html#tag-description"><description/></a>, <a class="xref" href="chap-Metadata.html#tag-metadata_license"><metadata_license/></a>.
</div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="chap-Metadata.html"><strong>Prev</strong>Chapter 2. Upstream Metadata</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-Metadata-ConsoleApplication.html"><strong>Next</strong>2.3. Console Applications</a></li></ul></body></html>
|