Commit 60a4c403 authored by Matthias Klumpp's avatar Matthias Klumpp
Browse files

docs: Clarify when/why to use .appdata.xml instead of .metainfo.xml extensions

The answer is: Pretty much use .metainfo.xml all the time, unless you
have a desktop-app in which case you may choose .appdata.xml (which will
likely be supported forever for legacy compatibility).
parent 6feb6b88
......@@ -35,9 +35,9 @@
</para>
<note>
<para>
Applications are a special case here, because they are usually treated differently by software centers (and also for historical reasons).
If your metainfo file contains an application, as described in <xref linkend="sect-Metadata-Application"/>, you may want to install it as
<filename>/usr/share/metainfo/%{id}.appdata.xml</filename>.
Component metadata of type <literal>desktop-application</literal> as described in <xref linkend="sect-Metadata-Application"/> can be installed as
<filename>/usr/share/metainfo/%{id}.appdata.xml</filename> (with an <filename>.appdata.xml</filename>) as well for historical reasons.
AppStream implementations will read the XML files as long as they end up in the right location on the filesystem.
</para>
</note>
<important>
......@@ -46,7 +46,7 @@
AppStream tools scan the <filename>/usr/share/appdata/</filename> path for legacy compatibility as well. It should not be used
anymore by new software though, even on older Linux distributions (like RHEL 7 and Ubuntu 16.04 LTS) the metainfo path is well
supported.
Support for the legacy path might be dropped completely in future.
Support for the legacy path will likely be dropped completely with a future AppStream 1.0 release.
</para>
</important>
......
......@@ -26,7 +26,7 @@
<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 <filename>.desktop</filename> file.
Applications can ship one or more files in <filename>/usr/share/metainfo/%{id}.appdata.xml</filename>.
Applications can ship one or more files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
</para>
<para>
Data will only be fetched from a desktop file if one <xref linkend="tag-dapp-launchable"/> tag is present to define a .desktop file ID. If multiple <literal>launch</literal> tags are
......@@ -38,6 +38,13 @@
You might want to take a look at <xref linkend="sect-Quickstart-DesktopApps"/> instead.
</para>
</note>
<note>
<para>
While <literal>desktop-application</literal> metadata is commonly stored in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename> (with a <filename>.metainfo.xml</filename> extension),
using a <filename>.appdata.xml</filename> extension is also permitted for this component type for legacy compatibility.
AppStream implementations will recognize either file type, as long as it ends up in the right location on the filesystem.
</para>
</note>
</section>
<section id="spec-appdata-filespec">
......
......@@ -21,12 +21,12 @@
<para>
To solve this, we have defined a new data file, which the upstream project can optionally translate using the same technique as
<ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop files</ulink> or GSetting schemas.
The application metainfo ("appdata") specification is a subset of the AppStream metadata (see <xref linkend="sect-AppStream-XML"/>) and extends
The application metainfo specification is a subset of the AppStream metadata (see <xref linkend="sect-AppStream-XML"/>) and extends
the generic component metadata with fields specific for applications (see <xref linkend="sect-Metadata-GenericComponent"/>).
</para>
<para>
The application-metainfo files override any values which are automatically fetched by the AppStream data generator.
Applications can ship one or more files in <filename>/usr/share/metainfo/%{id}.appdata.xml</filename>.
Applications can ship one or more files in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
</para>
<para>
Application metainfo files can - just like all other metainfo files - be translated. See the section about translation for more information about that.
......
......@@ -18,7 +18,7 @@
<title>For KDE developers</title>
<para>
If you are a KDE developer and using the KDE infrastructure with it's localization support, you need to do nothing
to get translated metadata. Just place your <filename>*.appdata.xml*</filename> or <filename>*.metainfo.xml*</filename> file
to get translated metadata. Just place your <filename>*.metainfo.xml*</filename> (or <filename>*.appdata.xml*</filename> file)
at a sane place, and the l10n-script will translate the file in-place automatically.
</para>
</note>
......@@ -67,10 +67,10 @@
the following code snippet:
</para>
<programlisting language="Makefile"><![CDATA[appstreamdir = $(datadir)/metainfo/
appstream_in_files = gedit.appdata.xml.in
appstream_in_files = gedit.metainfo.xml.in
appstream_DATA = $(appstream_in_files:.xml.in=.xml)
@INTLTOOL_XML_RULE@
EXTRA_DIST = $(appdata_in_files)
EXTRA_DIST = $(metainfo_in_files)
CLEANFILES = $(appstream_DATA)]]></programlisting>
<para>
The code assumes you are using the Intltool Automake code.
......@@ -84,10 +84,10 @@ CLEANFILES = $(appstream_DATA)]]></programlisting>
In case you want to use the macro provided by the AppStream-GLib library, you can use this code snippet:
</para>
<programlisting language="Makefile"><![CDATA[@APPSTREAM_XML_RULES@
appstream_in_files = gedit.appdata.xml.in
appstream_in_files = gedit.metainfo.xml.in
appstream_XML = $(appstream_in_files:.xml.in=.xml)
@INTLTOOL_XML_RULE@
EXTRA_DIST = $(appdata_in_files)
EXTRA_DIST = $(metainfo_in_files)
CLEANFILES = $(appstream_XML)]]></programlisting>
<para>
Make sure you have the additional AppStream macro installed.
......@@ -120,14 +120,14 @@ CLEANFILES = $(appstream_XML)]]></programlisting>
To extract a GNU Gettext <filename>.pot</filename> file from your XML file, run itstool with the follwing arguments (replacing "foo" with
your project name):
</para>
<programlisting language="Bash"><![CDATA[itstool -i as-metainfo.its -o $podir/foo_metadata.pot data/foo.appdata.xml]]></programlisting>
<programlisting language="Bash"><![CDATA[itstool -i as-metainfo.its -o $podir/foo_metadata.pot data/foo.metainfo.xml]]></programlisting>
<para>
You can then translate the <filename>.pot</filename> file using the standard methods for translating files like these. You obtain
<filename>.po</filename> files, which you can convert into <filename>.mo</filename> files (using msgfmt) like you would do with any
other localization. Then, you need to call <command>itstool</command> again, to create a translated version of the original XML file:
</para>
<programlisting language="Bash"><![CDATA[itstool -i as-metainfo.its -j data/foo.appdata.xml -o output/foo.appdata.xml $modir/*.mo]]></programlisting>
<programlisting language="Bash"><![CDATA[itstool -i as-metainfo.its -j data/foo.metainfo.xml -o output/foo.metainfo.xml $modir/*.mo]]></programlisting>
<para>
Please ensure that the <filename>.mo</filename> files in <filename>$modir</filename> are named with their language codes.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment