Commit a6ef5372 authored by Matthias Klumpp's avatar Matthias Klumpp
Browse files

docs: Explain why name/summary should not be omitted for app metainfo files

This was already made clear in the spec part of the documentation, but
the quickstart page was not up to date.
parent 60a4c403
...@@ -179,13 +179,17 @@ ...@@ -179,13 +179,17 @@
<term>&lt;name/&gt;</term> <term>&lt;name/&gt;</term>
<listitem> <listitem>
<para> <para>
While this tag is always requited for a generic component, for an application metainfo file it is not necessary, but only recommended. It is highly recommended to have this tag present and contain a name of your application as value.
You can omit this tag if you want the software center to have the same strings as defined in the <literal>Name</literal> field
of the <filename>.desktop</filename> file. In that case, one <xref linkend="qsr-app-launchable-info"/> tag must be present.
</para> </para>
<para> <para>
If no <literal>name</literal> tag and no <literal>Name</literal> field is present, the metadata In theory you can omit this tag and have the AppStream generator of a Linux distribution automatically use the <literal>Name</literal> field
is considered invalid and might be ignored by the AppStream generator. of the associated <filename>.desktop</filename> file (In which case one <xref linkend="qsr-app-launchable-info"/> tag must be present).
However, a large amount of tools expect the metainfo file to be complete and self-sufficient now, which is why omitting this tag will render it
invalid for tools like Flatpak and others use cases which do not involve a metadata preprocessing step.
</para>
<para>
If no <literal>name</literal> tag (and no <literal>Name</literal> desktop-entry field) is present, the metadata
is considered invalid and will be ignored by the AppStream generator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -194,15 +198,17 @@ ...@@ -194,15 +198,17 @@
<term>&lt;summary/&gt;</term> <term>&lt;summary/&gt;</term>
<listitem> <listitem>
<para> <para>
While this tag is always requited for a generic component, for a <literal>desktop-application</literal> metainfo file it is only essential It is highly recommended to have this tag present and contain a brief summary of what your application is about.
if the accompanying <filename>.desktop</filename> file does not have a <literal>Comment=</literal> field. Data from a .desktop file is only </para>
taken into consideration if one <xref linkend="qsr-app-launchable-info"/> tag is present. <para>
If the metainfo file has a <literal>summary</literal>, it wil override the value found in the <literal>Comment</literal> field of the In theory you can omit this tag and have the AppStream generator of a Linux distribution automatically use the <literal>Comment</literal> field
<filename>.desktop</filename> file. of the associated <filename>.desktop</filename> file (In which case one <xref linkend="qsr-app-launchable-info"/> tag must be present).
However, a large amount of tools expect the metainfo file to be complete and self-sufficient now, which is why omitting this tag will render it
invalid for tools like Flatpak and others use cases which do not involve a metadata preprocessing step.
</para> </para>
<para> <para>
If no <literal>summary</literal> tag and no <literal>Comment</literal> field is present, the metadata If no <literal>summary</literal> tag (and no <literal>Comment</literal> desktop-entry field) is present, the metadata
is considered invalid and might be ignored by the AppStream generator. is considered invalid and will be ignored by the AppStream generator.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
......
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