freedesktop.org

("xdg" abbreviates "X Desktop Group," a previous name of xdg-utils

Base Directories

Freedesktop.org Base Directory Specification

-> env | grep XDG
XDG_VTNR=1
XDG_SESSION_ID=6
XDG_MENU_PREFIX=xfce-
XDG_SESSION_PATH=/org/freedesktop/DisplayManager/Session1
XDG_SEAT_PATH=/org/freedesktop/DisplayManager/Seat0
XDG_CONFIG_DIRS=/etc/xdg
XDG_SEAT=seat0
XDG_DATA_DIRS=/usr/local/share:/usr/share
XDG_RUNTIME_DIR=/run/user/1000

User Directories

FDO/XDG defines several variables that applications can use to locate well-known user directories: DESKTOP, DOCUMENTS, DOWNLOAD, MUSIC, PICTURES, PUBLICSHARE, TEMPLATES, and VIDEOS. Ostensibly (to me anyway), each name is loosely but sufficiently self-documented by its meaning; FDO does not elaborate any intended use. An applications can thus flexibly interpret a name as it sees fit. System designers and end users can likewise resolve these names to directories as they wish.

These FDO/XDG environment variables are associated with directories under $HOME, typically, in file ~/.config/user-dirs.dirs:

-> cat ~/.config/user-dirs.dirs 
# This file is written by xdg-user-dirs-update

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"

XDG_VIDEOS_DIR="$HOME/Videos"

You can also use command xdg-user-dirs to look-up these associations:

-> xdg-user-dir DESKTOP
/home/ray/Desktop
-> xdg-user-dir DOWNLOAD
/home/ray/Downloads

More generally, file name "~/.config/user-dirs.dirs" derives from "$XDG_CONFIG_HOME/user-dirs.dirs" when $XDG_CONFIG_HOME has its default value.

You can customize these associations between FDO environment variables and your own directories by editing ~/.config/user-dirs.dirs. That file tells you what you need to know:

-> head --lines 6 ~/.config/user-dirs.dirs 
# This file is written by xdg-user-dirs-update
# If you want to change or add directories, just edit the line you're
# interested in. All local changes will be retained on the next run
# Format is XDG_xxx_DIR="$HOME/yyy", where yyy is a shell-escaped
# homedir-relative path, or XDG_xxx_DIR="/yyy", where /yyy is an
# absolute path. No other format is supported.

Alternatively, let command xdg-user-dirs-update do the job:

-> xdg-user-dirs-update --set MUSIC "$HOME/audio/music"
-> xdg-user-dir MUSIC
/home/ray/audio/music

If you want to nullify an FDO variable, set its value to $HOME/ (note trailing "/") or some other place:

-> xdg-user-dirs-update --set PUBLIC "$HOME/"
-> xdg-user-dir PUBLIC
/home/ray/

You cannot simply remove its definition from the configuration file. Absence of an entry revives the default definition and begets the default directory (see below).

As it turns out, xdg-user-dirs-update pulls additional duty. It is run (without arguments) during login to setup the FDO/XDG variables. It consults /etc/xdg/user-dirs.defaults to learn what variables to define and what default directories to use. But it also checks ~/.config/user-dirs.dirs for usere preferences overriding system defaults. If the latter file is missing or incomplete, xdg-user-dirs-update falls back to the system defaults.

# Clean slate
-> rm ~/.config/user-dirs.dirs
-> rmdir ~/{Desktop,Documents,Music,Pictures,Public,Templates,Videos}

# Refill slate
-> xdg-user-dirs-update 

# Review slate
-> grep '^XDG' ~/.config/user-dirs.dirs 
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_VIDEOS_DIR="$HOME/Videos"

# Verify slate
-> stat --format "%F %n" ~/{Desktop,Documents,Music,Pictures,Public,Templates,Videos}
directory /home/ray/Desktop
directory /home/ray/Documents
directory /home/ray/Music
directory /home/ray/Pictures
directory /home/ray/Public
directory /home/ray/Templates
directory /home/ray/Videos

More generally, file name "/etc/xdg/user-dirs.defaults" derives from "$XDG_CONFIG_DIRS/user-dirs.defaults" when $XDG_CONFIG_DIRS has its default value.

Desktop Entry Files

FDO provides a standardized desktop entry to describe an application for the sake of menus, panels, and file associations. A desktop entry is a simple configuration file specifying metadata that are used to list or launch an application via desktop tools. Such metadata include, for example, a program's name, icon, and executable. A desktop-entry file itself is a text file with extension desktop and a base name indicating the application, as in leafpad.desktop. Each property appears as a simple name-value pair. Here's the desktop entry describing Leafpad, for example:

[Desktop Entry]
Encoding=UTF-8
Name=Leafpad
Comment=Simple text editor
Comment[bg]=Опростен текстов редактор

Exec=leafpad %f
Icon=leafpad
Terminal=false
Type=Application
MimeType=text/plain;
Categories=GTK;Utility;TextEditor;
X-Desktop-File-Install-Version=0.21

Application Autostart

When establishing a new session for a user, the desktop's session manager may automatically start a selection of applications on the user's behalf. Desktop entry files under directories ~/.config/autostart (user) and /etc/xdg/autostart (system) determine candidate applications. For example:

-> ls -1 /etc/xdg/autostart
at-spi-dbus-bus.desktop
gnome-keyring-gpg.desktop
...
xfce4-clipman-plugin-autostart.desktop
...
xscreensaver.desktop

A desktop manager does not necessarily launch every application referenced by these .desktop files, however. Instead, it examines each file for optional keys Hidden, OnlyShowIn, and NotShowIn to decide whether or not to start the corresponding application. The session manager ignores any desktop entry with Hidden=true. It also ignores any .desktop file which omits the desktop environment's name (e.g. GNOME, KDE, Xfce) from the value of OnlyShowIn or lists that name for NotShowIn. A desktop entry may define only one of the keys OnlyShowIn and NotShowIn.

When the session manager finds two .desktop files with the same filename in both the user and system directories, it ignores the system version in favor of the user version. For example, desktop entry ~/.config/pulseaudio.desktop effectively overshadows any /etc/xdg/autostart/pulseaudio.desktop. Consequently, a configuration editor for autostart applications can override system defaults by putting suitably tuned desktop entry files in the user's autostart directory. For instance, Xfce (under Fedora 20) autostarts Print Queue Applet (print-applet.deskop) by default. When a user nixes this default in the settings editor for Xfce sessions (xfce4-session-settings), the editor simply creates desktop entry file ~/.config/autostart/print-applet.desktop with the single name-value pair Hidden=true. A user or script can likewise adjust the system defaults of /etc/xdg/autostart directly by copying any of those desktop entries to ~/.config/autostart and modifying the copies' name-value pairs. Similarly, a user can have the desktop session manager start applications in addition to the system defaults by creating corresponding desktop entries in ~/.config/autostart.

As a polite convenience, a package may include a desktop entry file under /etc/xdg/autostart yet specify Hidden=true so that the session manager does not start the corresponding application by default. Then, a configuration editor for the desktop environment can list the application as available for autostart and provide a check-box for the user to enable autostart. For example, Xfce's clipboard-manager package xfce4-clipman-plugin installs xfce4-clipman-plugin-autostart.desktop with Hidden=true under /etc/xdg/autostart, and Xfce's session-settings editor provides a check-box to enable the clipboard manager.

Xfce's session editor offers to autostart applications for which the desktop entry files have assigned key OnlyShowIn with a value omitting Xfce. It displays these in italic face at the end of the list of candidate applications. If the user elects to autostart such an application, the editor creates a desktop entry file in ~/.config/autostart with the single name-value pair X-XFCE-Autostart-Override=true.

Menus

Pacakge garcon

rpm -q --list garcon | grep -v locale
/etc/xdg/menus/xfce-applications.menu
...
/usr/share/desktop-directories/xfce-accessories.directory
/usr/share/desktop-directories/xfce-development.directory
/usr/share/desktop-directories/xfce-documentation.directory
/usr/share/desktop-directories/xfce-education.directory
/usr/share/desktop-directories/xfce-games.directory
/usr/share/desktop-directories/xfce-graphics.directory
/usr/share/desktop-directories/xfce-hardware.directory
/usr/share/desktop-directories/xfce-multimedia.directory
/usr/share/desktop-directories/xfce-network.directory
/usr/share/desktop-directories/xfce-office.directory
/usr/share/desktop-directories/xfce-other.directory
/usr/share/desktop-directories/xfce-personal.directory
/usr/share/desktop-directories/xfce-screensavers.directory
/usr/share/desktop-directories/xfce-settings.directory
/usr/share/desktop-directories/xfce-system.directory
...

Menus files are XML files with extension menu format

/etc/xdg/menus. ~/.config//xdg/menus. See fredesktop.org

Submenus: Desktop Entry Files

Menu Items

Each item in the Applications Menu has an associated desktop entry. The default desktop entry files for the system reside in directory /usr/share/applications (via package redhat-menus—I think) and a user's personal desktop files reside in ~/.local/share/applications. A personal desktop file overrides a system file of the same name. This precedence gives users a simple means to customize menu items. For example, a user can customize a menu entry simply by copying its system desktop file into ~/.local/share/applications and then modifying the personal copy accordingly. In particular, a user can prevent a menu item from appearing by adding NoDisplay=true to the personal copy of the desktop file.

When alacarte modifies a menu item, it copies the corresponding desktop file from the system directory, modifies it accordingly, and saves it as a personal entry under ~/.local/share/applications.

To drop an entry from the menu, copy its system desktop file to ~/.local/share/applications and add "NoDisplay=false" to the local copy. To display an existing desktop entry in the menu, copy its desktop file but add "NoDisplay=false" to the local copy.

a user can add an application to an existing menu by creating a personal desktop file describing the application.

See also: Desktop Menu Specification. Customizing Menus (GNOME).

File Associations

Desktop file mangers like Nautilus and Thunar allow a user to open a file by double-clicking (or similar) on the displayed name or icon of the target file. The application launched depends on the desktop's file associations. By default, freedesktop.org desktops use the associations given in /usr/share/applications/defaults.list. This configuration file sets associations for a recognized MIME type by listing one or more applications suitable for opening files of that type; the lists name desktop entry files to register applications. When a user selects a file to open via Nautilus or Thunar, for example, the choice of applications comes from the list in defaults.list for the MIME type of the selected file. The first application listed for a type becomes the default for that type. The text file defaults.list uses a simple and clear format.

Use a file manager to change the default application for opening files of a given (MIME) type. The details differ by file manager. For Nautilus, Thunar, and PCManFM, at least, start by right-clicking on a file of the desired type. In Thunar, select Open With and then Open with Other Application from the pop-up menus. In PCManFM, select Open With. In Nautilus with GNOME 3, select Properties from the menu, then click the Open With tab; with GNOME 2, select Open with Other Application from the menu.

When a user modifies the system defaults, as above, the new settings are saved in ~/.local/share/applications/mimeapps.list. (For GNOME 2, this file is named defaults.list again.) The choices in mimeapps.list override the system defaults. Edit this text file to manually adjust file associations; the format is simple and clear. It may be necessary to restart the file manager to load manual adjustments, depending on what application edits the file.

See also: MIME actions specification. Registering Applications for MIME Types (GNOME).

Panel

~/.gnome2/.panel2.d/default/launchers

See also: Panels (GNOME).

More on MIME

A desktop entry file can list the MIME types it can handle in a MimeType key, and utility update-desktop-database makes mimeinfo.cache. Do not edit mimeinfo.cache because it is modified by other applications.

Shared MIME information specification.