-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
266 lines (243 loc) · 11.3 KB
/
index.html
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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>AppData Specification</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="keywords" content="AppStream, AppData, Metadata, Linux, Applications" />
<meta name="description" content="AppData Specification" />
<meta name="author" content="Richard Hughes" />
<meta name="robots" content="index,follow" />
<link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="common.css" />
</head>
<body>
<center><img src="long-description.png" alt="[Screenshot of GNOME Software]"/></center>
<h1>Introduction:</h1>
<p>
Every software center that exists allows the user to look at screenshots
and a long description of the application before it is installed.
For most users it allows them to answer the question <i>Do I want to install this...</i>
</p>
<p>
In Linux, we have <b>none</b> of this data for the vast majority of our desktop
user-installable applications.
What we need to do is define a new data file, which the upstream project can
optionally translate using the same technique as GSetting schemas or
<a href="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop files</a>.
Rather than create a new schema from scratch, we'll be using a subset of the
<a href="http://www.freedesktop.org/wiki/Distributions/AppStream/">AppStream</a>
metadata proposal.
</p>
<p>
Since this data is per-application, rather than per-project or per-package we
can use the .desktop name as the ID for the data.
This means we can extract this data and add it to any
<a href="http://www.freedesktop.org/wiki/Distributions/AppStream/">AppStream</a>-or-similar
metadata consumed by the software center.
</p>
<h1>Specification:</h1>
<p>
Applications wishing to have long descriptions, screenshots and other useful things
are required to ship one or more files in <code>/usr/share/appdata/%{id}.appdata.xml</code>.
The <code>%{id}</code> is the same name as the installed .desktop file for the
application. This file will contain something like this:
</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<application>
<id type="desktop">gnome-power-statistics.desktop</id>
<licence>CC0</licence>
<name>Power Statistics</name>
<summary>Observe power management</summary>
<description>
<p>
Power Statistics is a program used to view historical and current battery
information and will show programs running on your computer using power.
</p>
<p>Example list:</p>
<ul>
<li>First item</li>
<li>Second item</li>
</ul>
<p>
You probably only need to install this application if you are having problems
with your laptop battery, or are trying to work out what programs are using
significant amounts of power.
</p>
</description>
<screenshots>
<screenshot type="default" width="800" height="600">http://www.hughsie.com/en_US/main.png</screenshot>
<screenshot width="800" height="600">http://www.hughsie.com/en_US/preferences.png</screenshot>
</screenshots>
<url type="homepage">http://www.gnome.org/projects/en_US/gnome-power-manager</url>
<updatecontact>[email protected]</updatecontact>
</application>
</pre>
<h1>Questions:</h1>
<a name="description-format"/><h3>What format should the description be?</h3>
<p>Important things to consider when writing the application description:</p>
<ul>
<li>Include 2-3 paragraphs of interesting easy to read prose.</li>
<li>Ensure you provide a description of what the application actually does.</li>
<li>Describe any important features.</li>
<li>Do not use possily trademarked product names when refering to competitors.</li>
<li>Break down each paragraph into easily translated paragraphs.</li>
<li>Use lists sparingly.</li>
<li>Never refer to installable items as packages.</li>
<li>Never start the first sentance with <i>This application...</i></li>
<li>Try not use more than 100 words.</li>
<li>Do not be too geeky. Aim for an intelligent semi-technical reader.</li>
<li>Don't mention what language an application is written in, users don't care</li>
<li>Only mention what the application can do now, rather than what is planned</li>
<li>Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.</li>
</ul>
<a name="duplicate-name"/><h3>Why include Name and Summary data if it's already in the .desktop file?</h3>
<p>
You can omit the <code><name></code> and <code><summary></code> tags if
you want the software center to have the same strings as the desktop menu.
In some cases it might be required to have a different name in the app-store,
but most <code>appdata.xml</code> files will not need these tags.
</p>
<a name="translation"/><h3>How do I translate this data?</h3>
<p>
If you ship an <code>.xml.in</code> file rather than an <code>.xml</code> file,
you can use a tool like itstool to translate the data.
We've provided a <a href="appdata.its"><code>appdata.its</code></a> file
for convenience.
</p>
<p>
Translated descriptions are a really nice feature, as only a fraction of the
userbase installing application will be able to understand English text,
but for the technical preview we'll probably only be including the en_US text.
</p>
<p>
After GNOME 3.10 (when most projects can add new strings) I'll be contacting
people who have already added AppData files with more detailed instructions on
how to setup the files for translation.
</p>
<a name="screenshot-format"/><h3>What format are the screenshots?</h3>
<p>
Screenshots are only fetched by the software center when the long description
is shown.
Only translate these if a corresponding translated screenshot exists.
Screenshots should typically be ~800px wide and should not exceed 1Mb in
size.
Either a lossy format '.jpg' or lossless '.png' format is permitted.
</p>
<a name="screenshots"/><h3>Are screenshots required?</h3>
<p>
No, but we'd really hope you could ship at least one.
A screenshot is a really good way of <i>previewing</i> the application before
it is installed and a really good way of increasing your userbase.
</p>
<a name="package"/><h3>Why not just use the package description?</h3>
<p>
Different distros cut and join different source packages in different ways,
plus, it's not typically translated.
</p>
<a name="doap"/><h3>Why not just use the DOAP description?</h3>
<p>
This is one file per-project and is not suitable when one tarball will install
several applications. It's also not translatable.
</p>
<a name="web-service"/><h3>Why not just use a centralized web service?</h3>
<p>
Put simply, we don't have the resources to moderate, check and translate each
string for every application. We don't have the legal framework so that
non-free applications could also ship application data.
</p>
<p>
The upstream project is in a much better place to describe itself, and the
upstream project is able to use it's existing localization and translation teams.
Also, things like the screenshot will change as the project is updated, and
not all distros ship the same version of an application.
We also want the long description to come up immediately, and be searchable,
so we can't really use a web service in that case.
Additionally, different distros have different policies on trademarks.
</p>
<a name="how-about-no"/><h3>What happens if I don't ship this file?</h3>
<p>
The GNOME Software Center currently shows a nag message that the upstream project
doesn't ship the additional data.
Additionally, we will penalize apps that do not ship the extra metadata by showing
them lower in the search results.
</p>
<a name="other-data"/><h3>What other data should I include in the file?</h3>
<p>
At this moment we're trying to do the bare minimum for a software center technical
preview.
In the future I can totally see this file being used to express what portals
are required (i.e. <i>Firefox needs access to your addressbook</i>) and other
useful things.
I'll update this page when we've got some more concrete use-cases.
</p>
<a name="updatecontact"/><h3>What is <code>updatecontact</code> used for?</h3>
<p>
AppData is a new standard, and we'll likely be adding extra metadata in the
future. If you include the <code><updatecontact></code> tag then someone
will send an email when the standard is updated, detailing the new fields that
you may or may not want to add to your <code>appdata.xml</code> file.
We're not expecting to do this more than 4 times a year, so don't expect a
deluge of email.
</p>
<p>
<b>TIP:</b>Use <code>_at_</code> rather than <code>@</code> if you're worried
about the email address being harvested.
</p>
<a name="why-xml"/><h3>Why XML and not JSON/other?</h3>
<p>
AppData is a subset of the <a href="http://www.freedesktop.org/wiki/Distributions/AppStream/">AppStream</a>
schema, which is also XML.
</p>
<a name="licence"/><h3>Is the <code>licence</code> tag supposed to be my project licence?</h3>
<p>
No. The <code><licence></code> tag is indicating the licence that you
are releasing the AppData text as.
By ommitting the licence value would probably mean your data would not be
incorporated into the AppStream metadata. Permissible licences include:
</p>
<ul>
<li>CC0</li>
<li>CC BY</li>
<li>CC BY-SA</li>
</ul>
<a name="use"/><h3>Where will this data be used?</h3>
<p>
We will scrape this data when building and composing distributions, and depending
on the implementation will either use an OCS server or directly copy the AppData
data into the AppStream metadata.
</p>
<a name="validate"/><h3>How do I know if my appdata XML is correct?</h3>
<p>
You can validate it using a <a href="http://relaxng.org/">RELAX NG</a> schema
available in <a href="appdata.rng">XML syntax</a> and
<a href="appdata.rnc">compact syntax</a> form. This can be used with tools like
<a href="http://xmlsoft.org/xmllint.html">xmllint</a>,
<a href="http://www.thaiopensource.com/relaxng/jing.html">Jing</a> and the
instantly validating
<a href="http://www.thaiopensource.com/nxml-mode/">nXML-mode</a> for Emacs.
</p>
<p>
Note: This is available as a possibly helpful tool, it should not be seen
as normative. It is possible that the validation schema is too strict or too lax,
and it might fail to be updated as the Appdata project evolves.
</p>
<a name="example"/><h3>Have you got a real world example?</h3>
<p>
See the commit that added the AppData metadata to
<a href="example.patch">gnome-power-manager</a>.
</p>
<a name="install-appdata"/><h3>Should I install the appdata files?</h3>
<p>
You should install the your appdata file to <code>/usr/share/appdata/</code>.
This is the standard search path that application installer tools use when
there is no distro-specific appstream metadata available.
</p>
<p class="footer">
This page is managed by <a href="mailto:[email protected]">Richard Hughes</a>
and is <a href="http://validator.w3.org/check/referer" target="_blank">optimized</a>
for <a href="http://www.w3.org/" target="_blank">standards</a>.
</p>
<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
<br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/><br/>
</body>
</html>