⌛ This hasn't been updated for a while, so could be outdated (particularly if it's about something that evolves constantly, such as software or research).

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

Mostly "stuff that adheres to freedesktop, and some details to getting it to work in practice"

xdg

Among other things, freedesktop's xdg ('Cross Desktop Group') unifies/standardizes how desktop environments would recognize file types, how to open them, how to preview them.

On /etc/xdg (and /etc/skel)

✎ This article/section is a stub — some half-sorted notes, not necessarily checked, not necessarily correct. Feel free to ignore, or tell me about it.

A bunch of this sits in /etc/xdg, which e.g.

set application icons you start off with
avoid creation of Videos, Music, etc. https://wiki.archlinux.org/index.php/Xdg_user_directories
disable the online search things in Unity - [1] [2] [3]

If, in lieu of cleanup, you want to know exactly what packages these contents come from, try:

find /etc/skel /etc/xdg | xargs apt-file search

https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

xdg user dirs

xdg-utils

xdg-utils is a set of tools that helps apps integrate with user's desktop environment, regardless of which one.

xdg-open

https://wiki.archlinux.org/title/Xdg-utils#xdg-open

xdg-settings

xdg-mime

.desktop files

Example content of a .desktop file to launch an application:

[Desktop Entry]
Version=1.0
Name=ProgramName
Comment=What it does
Exec=/path/to/executable
Icon=/path/to/icon.png
Terminal=false
Type=Application
Categories=Utility

Notes:

Exec path may be relative if it's in the PATH
Icon path may be
- absolute path, OR a relative and extensionless name referring to something in /usr/share/pixmaps (more specifically, see the resolution mentioned in [4])
- image format: xpm, png, svg. The last may not be supported by everything(?) (verify)

Version refers to version of the .desktop standard. Current version is 1.0. This key is not required.

List of further keys: http://standards.freedesktop.org/desktop-entry-spec/latest/ar01s05.html

it seems GNOME only accepts it as an application selectable under e.g. "open with other application" if you adhere to the file naming (verify)

Findable by the launcher

If you want the launcher to offer these when you search for them, put .desktop files in:

For all users:

/usr/share/applications/

For individual users:

/home/username/.local/share/applications/

It seems it accepts subdirectories and symlinks, which can make finer-grained sharing of .desktop files easier.

Icons on your actual desktop

Put a copy or symlink in ~/Desktop and ensure it is executable (only then will it be parsed, executable, and show the right icon).

icons in the GNOME favorites/dock

These are the favorites in your dock / launcher

Once you can find them, you can add them with the mouse.

If you, as an admin, want to alter them mechanically, this varies with the version of GNOME, and with whether you want to do it via an API or try to get it right on the command line.

TODO: figure out more, post script

MIME and such

MIME type detection

In practical terms it's approximately

writing a file like /usr/share/mime/packages/mymime.xml
running update-mime-database /usr/share/mime.

That file (see specs here) would look something like:

<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
  <mime-type type="image/x-stack">
    <sub-class-of type="image/raw"/>
    <glob pattern="*.img"/>
    <magic priority="50">
      <match type="little32" offset="0" value="0"/>
    </magic>
    <generic-icon name="image-x-generic">
    <comment>raw image stack</comment>
  </mime-type>
</mime-info>

match elements have:

type- string, host16, host32, big16, big32, little16, little32 or byte.
offset - single byte offset, or from:to range (inclusive)
value - thing to check, in the format relevant for the type
mask (optional) - bitwise AND before checking(verify)

Logic:

OR rules by putting them at the same level
AND rules by nesting them

Priority - lets you deal with more and less specific variants. For example, modern office documents are zip files, meaning their matching should have a higher priority than zip archives in general.

(globs can have weight)

While debugging you probably want to: xdg-mime query filetype filename

Application associations

Thumbnailer

A thumbnailer is a program that takes:

a target size
a filename or URL-style path
an output file

...and writes a PNG image to that output file.

They are hooked in by adding a file like /usr/share/thumbnailers/mymime.thumbnailer with:

[Thumbnailer Entry]
MimeType=application/x-mymime;
Exec=my-thumbnailer %s %f %o

...where

those parameters

%s is the size (typically 128 or 256), though the thumbnailer will size down if yours doesn't

%f is a file path

%u is an URL-style path (usually you choose either %f or %u)

%o is the output file to write to (probably a random filename in /tmp)

There's a bunch of footnotes to URLs, TryExec, etc.

If you are debugging a thumbnailer, you may wish to empty earlier attempts, including:

Cached thumbnailes under ~/.cache/thumbnails/
Cached failures in ~/.cache/thumbnails/fail/gnome-thumbnail-factory/

Freedesktop, GNOME, and KDE notes

Contents

xdg