Rename instances of appdata to metainfo

docs/conventions.rst

@@ -68,19 +68,19 @@ For some practical examples of bad IDs
   domain. Instead you should use ``io.github`` or ``io.gitlab`` as
   shown above.
 
-AppData files
-`````````````
-AppData files provide metadata about applications, which is
+MetaInfo files
+``````````````
+MetaInfo files provide metadata about applications, which is
 used by application stores (such as Flathub, GNOME Software
 and KDE Discover).
 
 The `Freedesktop AppStream specification
 <https://www.freedesktop.org/software/appstream/docs/>`_ provides a complete
-reference for providing AppData. You can use the online
+reference for providing MetaInfo. You can use the online
 `AppStream MetaInfo Creator <https://www.freedesktop.org/software/appstream/metainfocreator/>`_
 to generate a basic file.
 
-AppData files should be named with the application ID and the ``.metainfo.xml``
+MetaInfo files should be named with the application ID and the ``.metainfo.xml``
 file extension, and should be placed in ``/app/share/metainfo/``. For example::
 
   /app/share/metainfo/org.gnome.Dictionary.metainfo.xml
@@ -89,7 +89,7 @@ A legacy convention of having the ``.appdata.xml`` installed in ``/app/share/app
 is also accepted as well, and ``flatpak-builder`` will check either directory with
 either extension.
 
-The ``appstream-util validate-relax`` command can be used to check AppData
+The ``appstreamcli validate --explain`` command can be used to check MetaInfo
 files for errors.
 
 Application icons
@@ -116,6 +116,16 @@ icons are of size ``scalable``::
 
   /app/share/icons/hicolor/scalable/apps/org.gnome.Dictionary.svg
 
+Flatpak will export the following icon name patterns:
+``$FLATPAK_ID, $FLATPAK_ID.foo, $FLATPAK_ID-foo``. They may end with an
+extension suffix like ``.png, .svg``. Exported icons can be found in the
+``icons`` subfolder of ``$HOME/.local/share/flatpak/exports/share`` or
+``/var/lib/flatpak/exports/share`` depending on system or user install.
+
+The distribution usually appends those paths to ``$XDG_DATA_DIRS`` on
+host when installing the ``flatpak`` package. Unless an icon is exported
+by Flatpak, host applications cannot access it.
+
 Desktop files
 `````````````
 
@@ -137,14 +147,31 @@ A minimal desktop file should contain at least the application's *name*,
 
   [Desktop Entry]
   Name=Gnome Dictionary
-  Exec=org.gnome.Dictionary
+  Exec=gnome-dictionary
   Type=Application
   Icon=org.gnome.Dictionary
-  Categories=GNOME;GTK;Office;Dictionary;
+  Categories=Office;Dictionary;
 
 The ``desktop-file-validate`` command can be used to check for errors in
 desktop files.
 
+The ``Exec`` key of the desktop files is rewritten by Flatpak  when installing
+an app. The original value of the key becomes the value of the ``--command``
+argument like so::
+
+  Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=gnome-dictionary org.gnome.Dictionary
+
+Flatpak will export the following desktop filename patterns:
+``$FLATPAK_ID.desktop, $FLATPAK_ID.foo.desktop, $FLATPAK_ID-foo.desktop``.
+Exported desktop files can be found in the ``applications`` subfolder of
+``$HOME/.local/share/flatpak/exports/share`` or
+``/var/lib/flatpak/exports/share`` depending on system or
+user install.
+
+The distribution usually appends those paths to ``$XDG_DATA_DIRS`` on
+host when installing the ``flatpak`` package. Unless a desktop file is
+exported by Flatpak, host applications cannot access it.
+
 Exporting through extra-data
 ----------------------------
 

docs/first-build.rst

@@ -107,7 +107,8 @@
 
 In order for your application to show up in application stores while testing with a local repository, you might have
 to run ``flatpak build-update-repo repo``.
-For more information how to publish to application stores see `Appdata files <https://docs.flatpak.org/en/latest/freedesktop-quick-reference.html#appdata-files>`_.
+
+For more information how to publish to application stores see `MetaInfo files <https://docs.flatpak.org/en/latest/conventions.html#metainfo-files>`_.
 
 7. Install the app
 ------------------

docs/hosting-a-repository.rst

@@ -92,7 +92,7 @@
 .. code-block:: yaml
 
   variables:
-    # Application id of the app, should be same as id used in flatpak manifest and appdata
+    # Application id of the app, should be same as id used in flatpak manifest and MetaInfo
     APP_ID: tld.vendor.app_name
     # Location of the flatpak manifest, root of git repository
     MANIFEST_PATH: $CI_PROJECT_DIR/${APP_ID}.yaml
@@ -315,7 +315,7 @@
 the application. Updates will be fetched when running ``flatpak update`` 
 if they are available.
 
 11. You can set up a `pipeline schedule <https://docs.gitlab.com/ee/ci/pipelines/schedules.html>`_, 
     optionally to automatically check for updates using 
     `flatpak-x-checker <https://github.com/flathub/flatpak-external-data-checker>`_ 
     and send PRs to the repo.

docs/manifests.rst

@@ -56,7 +56,7 @@ the manifest:
 
 - ``rename-icon`` - rename the application icon
 - ``rename-desktop-file`` - rename the ``.desktop`` filename
-- ``rename-appdata-file`` - rename the AppData file
+- ``rename-appdata-file`` - rename the MetaInfo file
 
 Each of these properties accepts the name of the source file to be
 renamed. ``flatpak-builder`` then automatically renames the file to match

docs/reference.rst

@@ -10,7 +10,6 @@ Reference documentation for flatpak, flatpak-builder and libflatpak.
    flatpak-builder-command-reference
    available-runtimes
    sandbox-permissions-reference
-   freedesktop-quick-reference
    under-the-hood
    libflatpak-api-reference
    portal-api-reference