gnome-session MIME type associations
====================================

MIME type (media type, content type) associations can be annoying to
maintain by hand, because apps can support many MIME types and change
their set of supported MIME types over time, so instead they are generated
by a script.

Upstream's data/gnome-mimeapps.list
-----------------------------------

Upstream's data/gnome-mimeapps.list is generated on a "GNOME
OS" image by listing all the installed apps, treating them
as the preferred apps, and applying a few quirks to correct
for situations that would otherwise be mis-handled. See
https://gitlab.gnome.org/GNOME/gnome-build-meta/-/blob/master/files/gnome-mimeapps/quirks.toml

In Debian we do not build gnome-session in an environment that has every
GNOME app preinstalled, so we cannot take exactly this approach.

gnome-mimeapps subproject
-------------------------

debian/gnome-mimeapps/ is a subtree containing experimental code
from a GNOME contributor to generate distro-customized versions
of data/gnome-mimeapps.list, as suggested in the header of
data/gnome-mimeapps.list.

Maintenance:

    # once per checkout
    git remote add --no-tags gnome-mimeapps https://gitlab.gnome.org/heftig/gnome-mimeapps.git
    git fetch gnome-mimeapps

    # only needed the first time
    git fetch gnome-mimeapps
    git subtree add --prefix=debian/gnome-mimeapps gnome-mimeapps/main

    # to update
    git fetch gnome-mimeapps
    git subtree merge --prefix=debian/gnome-mimeapps gnome-mimeapps/main

debian/mimeapps/*.conf: vendor configuration
--------------------------------------------

These are the "source code" for gnome-mimeapps.list. Specifically, they are
input for build-mimeapps.py. See its source code for the format.

debian.conf is the default, but other vendors can use $(DEB_VENDOR).conf
if desired.

debian/mimeapps/upstreamish.conf: approximately upstream configuration
----------------------------------------------------------------------

This is an attempt to replicate the upstream gnome-mimeapps.list using
heftig's script: it does not produce *exactly* the same results, but
it's very close. It can be used to compare upstream configuration with
Debian's downstream configuration.

debian/mimeapps/upstream-reference.list is generated by editing
data/gnome-mimeapps.list programmatically to make it more similar
to gnome-mimeapps.list, for easier diffs. This lets us see what the
differences are and attempt to minimize them. If you run

    make -C debian/mimeapps upstreamish.conf

it will automatically show you a diff.

debian/mimeapps/*.desktop: cached app info
------------------------------------------

These are cached copies of the small subset of each .desktop file
that we need here, containing only the MimeType field. This allows
build-mimeapps.py to be run without needing to have all of these packages
actually installed on the local system.

On a system with the relevant packages installed, they can be updated with:

    make -f debian/mimeapps update-desktop-files

Alternatively, they can be derived from AppStream metadata, for example if
/var/lib/apt/lists/deb.debian.org_debian_dists_sid_main_dep11_Components-amd64.yml.gz
contains:

    Launchable:
      desktop-id:
      - org.gnome.SoundJuicer.desktop
    Provides:
      mediatypes:
      - x-content/audio-cdda

then we can create debian/mimeapps/org.gnome.SoundJuicer.desktop containing:

    [Desktop Entry]
    MimeType=x-content/audio-cdda;

Or if necessary they can be hand-edited based on upstream source code.
