summaryrefslogtreecommitdiffstats
path: root/desktop-entry
diff options
context:
space:
mode:
Diffstat (limited to 'desktop-entry')
-rw-r--r--desktop-entry/.cvsignore2
-rw-r--r--desktop-entry/ChangeLog182
-rw-r--r--desktop-entry/desktop-entry-spec.xml1392
3 files changed, 1576 insertions, 0 deletions
diff --git a/desktop-entry/.cvsignore b/desktop-entry/.cvsignore
new file mode 100644
index 0000000..e2bf8b5
--- /dev/null
+++ b/desktop-entry/.cvsignore
@@ -0,0 +1,2 @@
+*.ps
+*.html
diff --git a/desktop-entry/ChangeLog b/desktop-entry/ChangeLog
new file mode 100644
index 0000000..7113101
--- /dev/null
+++ b/desktop-entry/ChangeLog
@@ -0,0 +1,182 @@
+2008-09-12 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: reword sentence about characters allowed in
+ key names to avoid some ambiguity.
+ Patch by Simon McVittie <simon.mcvittie@collabora.co.uk>
+
+2008-03-04 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: bump version to 1.1-draft, so we can publish
+ it. See http://bugs.freedesktop.org/show_bug.cgi?id=14097
+
+2007-09-10 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: fix Icon key in example: it was using the
+ .png extension for an icon name. Which is wrong :-)
+
+2007-07-27 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: don't say that the files are encoded as
+ lines of 8-bit characters, which is wrong for UTF-8. Use something a
+ bit better proposed by Matthias Clasen <mclasen@redhat.com>
+ Bug #11417.
+
+2007-05-30 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: s/DESKTOP_LAUNCH_ID/DESKTOP_STARTUP_ID/
+ Thanks to Dan Winship <danw@gnome.org> for catching this.
+ Bug #11081.
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: scanf behavior is locale-dependent, and the
+ numeric type shouldn't be. Specify that the value is a floating point
+ number as recognized by scanf in the C locale.
+ Thanks to Dan Winship <danw@gnome.org> for catching this.
+ http://lists.freedesktop.org/archives/xdg/2007-April/009732.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: clarify description for the TryExec key.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009556.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: change "the $PATH" to "the $PATH environment
+ variable".
+ http://lists.freedesktop.org/archives/xdg/2007-March/009552.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: improve the description of the Comment key.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009440.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: a desktop file of type Application should
+ always have an Exec key. Same for Link Type and URL key.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: desktop files of type Directory have a
+ .directory extension right now (at least in GNOME), but according to
+ the spec, this is wrong. The patch fixes this. Also, it removes a
+ small part of text explaining the name of a desktop file describing a
+ directory.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml:clarify a bit the text about keys that only
+ makes sense in a specific context. Also, state that the keys should
+ not be used outside of this context. For example, the URL key should
+ not be present if the type is not Link.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: small typo
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: this changes the type of the version from
+ numeric to string. It's needed if we consider the possibility that
+ there are some desktop entry files out there using 0.9.x as a value
+ for this key. The change doesn't break anything.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: UnmountIcon is a localestring key.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-04-28 Vincent Untz <vuntz@gnome.org>
+
+ * desktop-entry-spec.xml: clarify that lists should always end with a
+ semicolon, even if there's only one value.
+ http://lists.freedesktop.org/archives/xdg/2007-March/009437.html
+
+2007-02-06 Waldo Bastian <waldo.bastian@intel.com>
+ * Clearify that %U may result in either local paths or file: URLs
+ * Deprecate %d, %n, %D and %N. They aren't usable on Gnome and
+ you can do the same with dirname and basename in a script.
+ * Clearify that %f, %u, %F or %U should only be used once.
+ * Clearify that these codes should be ignored if there is no file
+ to open.
+ * Forbid the use of field codes in quoted arguments.
+ * Clearify that %F and %U should only be used as a stand alone argument.
+ * Bumped version to 1.0
+
+2006-10-30 Waldo Bastian <waldo.bastian@intel.com>
+ * Remove equal sign from reserved characters in Exec args
+ * Add backslash to list of reserved characters in Exec args
+
+2006-10-04 Waldo Bastian <waldo.bastian@intel.com>
+ * Deprecate %v, it is FSDevice specific
+
+2006-08-30 Waldo Bastian <waldo.bastian@intel.com>
+ * list FSDevice type as KDE specific
+ * refer to Icon Theme Specification
+
+2006-08-22 Waldo Bastian <waldo.bastian@intel.com>
+ * clarification of Exec key
+ * correction of StartupWMClass, clarify StartupNotify (Lubos Lunak)
+ * deprecate SortOrder and FilePattern key (Vincent Untz)
+ * remove section on "MIME Type caching" from spec (Vincent Untz)
+ * groups and keys must be unique (Vincent Untz)
+ See http://lists.freedesktop.org/archives/xdg/2006-August/008446.html
+
+2006-05-28 Vincent Untz <vuntz@gnome.org>
+ * cleanup of text and some reorg for clearity
+ * move all of the legacy-mixed encoding stuff to the appendix
+ * deprecate the Swallow* keys
+ * improve definition of group headers
+ * reorder the list of standard keys so they are sorted by type
+ See http://lists.freedesktop.org/archives/xdg/2006-May/008131.html
+
+Tue Jul 13 18:04:11 2004 Jonathan Blandford <jrb@gnome.org>
+
+ * desktop-entry-spec.xml: Update the MIME description to make it
+ more relevent.
+
+2004-04-19 Mark McLoughlin <mark@skynet.ie>
+
+ Pointed out by Ville Skyttä <ville.skytta@iki.fi>
+
+ * desktop-entry-spec.xml: fix minor typo.
+
+2004-04-18 Mark McLoughlin <mark@skynet.ie>
+
+ Patch from Ville Skyttä <ville.skytta@iki.fi>
+
+ * desktop-entry-spec.xml: editorial changes, fixes for
+ typos and general cleanups.
+
+Mon Jul 7 18:26:14 2003 Owen Taylor <otaylor@redhat.com>
+
+ * destop-entry-spec.sgml: Merge changes by Havoc
+ Pennington that had been made in web module:
+
+ 2002/04/20: add changes posted to xdg-list a while back
+
+Sat Aug 24 17:00:48 2002 Owen Taylor <otaylor@redhat.com>
+
+ * desktop-entry-spec.sgml: In legacy-mixed table, fix duplicate
+ pt entry, language code for Armenian. Make explicit that
+ language-country locale tags can match a single language in
+ the table. (Pablo Saratxaga)
+
+Tue Mar 13 12:37:03 2001 Owen Taylor <otaylor@redhat.com>
+
+ * 0.9.3
+
+ * Reworked the description of encoding handling for
+ Legacy-Mixed for clarity and added a bit more details
+ on how encoding-matching should be done.
+
+Thu Mar 8 17:42:05 2001 Owen Taylor <otaylor@redhat.com>
+
+ * Import into CVS.
+
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
new file mode 100644
index 0000000..7d99d0a
--- /dev/null
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -0,0 +1,1392 @@
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+ ]>
+<article id="index">
+ <articleinfo>
+ <title>Desktop Entry Specification</title>
+ <releaseinfo>Version 1.1-draft</releaseinfo>
+ <date>4 Mar 2008</date>
+ <authorgroup>
+ <author>
+ <firstname>Preston</firstname>
+ <surname>Brown</surname>
+ <affiliation>
+ <address>
+ <email>pbrown@kde.org</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Jonathan</firstname>
+ <surname>Blandford</surname>
+ <affiliation>
+ <address>
+ <email>jrb@redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Owen</firstname>
+ <surname>Taylor</surname>
+ <affiliation>
+ <address>
+ <email>otaylor@gtk.org</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Vincent</firstname>
+ <surname>Untz</surname>
+ <affiliation>
+ <address>
+ <email>vuntz@gnome.org</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Waldo</firstname>
+ <surname>Bastian</surname>
+ <affiliation>
+ <address>
+ <email>waldo.bastian@intel.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </articleinfo>
+
+ <sect1 id="introduction">
+ <title>Introduction</title>
+ <para>
+ Both the KDE and GNOME desktop environments have adopted a similar
+ format for "desktop entries", or configuration files describing how a
+ particular program is to be launched, how it appears in menus, etc.
+ It is to the larger community's benefit that a unified standard be
+ agreed upon by all parties such that interoperation between the two
+ environments, and indeed any additional environments that implement
+ the specification, becomes simpler.
+ </para>
+ </sect1>
+ <sect1 id="basic-format">
+ <title>Basic format of the file</title>
+ <para>
+ Desktop entry files should have the <filename>.desktop</filename>
+ extension, except for files of <varname>Type</varname>
+ <constant>Directory</constant> which should have the
+ <filename>.directory</filename> extension. Determining file type on basis
+ of extension makes determining the file type very easy and quick.
+ When no file extension is present, the desktop system should
+ fall back to recognition via "magic detection".
+ </para>
+ <para>
+ Desktop entry files are encoded in UTF-8. A file is interpreted as a
+ series of lines that are separated by linefeed characters. Case is
+ significant everywhere in the file.
+ </para>
+ <para>
+ Compliant implementations MUST not remove any fields from the file,
+ even if they don't support them. Such fields must be maintained in a
+ list somewhere, and if the file is "rewritten", they will be included.
+ This ensures that any desktop-specific extensions will be preserved
+ even if another system accesses and changes the file.
+ </para>
+ <sect2 id="comments">
+ <title>Comments</title>
+ <para>
+ Lines beginning with a <literal>#</literal> and blank lines are
+ considered comments and will be ignored, however they should be
+ preserved across reads and writes of the desktop entry file.
+ </para>
+ <para>
+ Comment lines are uninterpreted and may contain any character
+ (except for LF). However, using UTF-8 for comment lines that
+ contain characters not in ASCII is encouraged.
+ </para>
+ </sect2>
+ <sect2 id="group-header">
+ <title>Group headers</title>
+ <para>
+ A group header with name <literal>groupname</literal> is a line in the
+ format:
+ </para>
+ <programlisting>[groupname]</programlisting>
+ <para>
+ Group names may contain all ASCII characters except for
+ <literal>[</literal> and <literal>]</literal> and control characters.
+ </para>
+ <para>
+ Multiple groups may not have the same name.
+ </para>
+ <para>
+ All <literal>{key,value}</literal> pairs following a group header until
+ a new group header belong to the group.
+ </para>
+ <para>
+ The basic format of the desktop entry file requires that there be
+ a group header named <literal>Desktop Entry</literal>. There may
+ be other groups present in the file, but this is the most
+ important group which explicitly needs to be supported. This
+ group should also be used as the "magic key" for automatic MIME
+ type detection. There should be nothing preceding this group in
+ the desktop entry file but possibly one or more comments.
+ </para>
+ </sect2>
+ <sect2 id="entries">
+ <title>Entries</title>
+ <para>
+ Entries in the file are <literal>{key,value}</literal> pairs in the
+ format:
+ </para>
+ <programlisting>Key=Value</programlisting>
+ <para>
+ Space before and after the equals sign should be ignored; the
+ <literal>=</literal> sign is the actual delimiter.
+ </para>
+ <para>
+ Only the characters <literal>A-Za-z0-9-</literal> may be used in
+ key names.
+ </para>
+ <para>
+ As the case is significant, the keys <varname>Name</varname> and
+ <varname>NAME</varname> are not equivalent.
+ </para>
+ <para>
+ Multiple keys in the same group may not have the same name. Keys in
+ different groups may have the same name.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="value-types">
+ <title>Possible value types</title>
+ <para>
+ The value types recognized are <literal>string</literal>,
+ <literal>localestring</literal>,
+ <literal>boolean</literal>, and
+ <literal>numeric</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Values of type <literal>string</literal> may contain all ASCII
+ characters except for control characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Values of type <literal>localestring</literal> are user displayable,
+ and are encoded in UTF-8.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Values of type <literal>boolean</literal> must either be the string
+ <literal>true</literal> or <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Values of type <literal>numeric</literal> must be a valid floating
+ point number as recognized by the <literal>%f</literal> specifier for
+ <function>scanf</function> in the <literal>C</literal> locale.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The escape sequences <literal>\s</literal>, <literal>\n</literal>,
+ <literal>\t</literal>, <literal>\r</literal>, and
+ <literal>\\</literal> are supported for values of type
+ <literal>string</literal> and <literal>localestring</literal>, meaning
+ ASCII space, newline, tab, carriage return, and backslash, respectively.
+ </para>
+ <para>
+ Some keys can have multiple values. In such a case, the value of the key
+ is specified as a plural: for example, <literal>string(s)</literal>. The
+ multiple values should be separated by a semicolon, and the value of the
+ key should have a semicolon as trailing character. Semicolons in these
+ values need to be escaped using <literal>\;</literal>.
+ </para>
+ </sect1>
+ <sect1 id="localized-keys">
+ <title>Localized values for keys</title>
+ <para>
+ Keys with type <literal>localestring</literal> may be postfixed by
+ [<replaceable>LOCALE</replaceable>],
+ where <replaceable>LOCALE</replaceable> is the locale type of the
+ entry. <replaceable>LOCALE</replaceable> must be of the form
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable>.<replaceable>ENCODING</replaceable>@<replaceable>MODIFIER</replaceable></literal>,
+ where
+ <literal>_<replaceable>COUNTRY</replaceable></literal>,
+ <literal>.<replaceable>ENCODING</replaceable></literal>,
+ and <literal>@<replaceable>MODIFIER</replaceable></literal>
+ may be omitted. If a postfixed key occurs, the same
+ key must be also present without the postfix.
+ </para>
+ <para>
+ When reading in the desktop entry file, the value of the key is
+ selected by matching the current POSIX locale for the
+ <varname>LC_MESSAGES</varname> category against the
+ <replaceable>LOCALE</replaceable> postfixes of all occurrences
+ of the key, with the
+ <literal>.<replaceable>ENCODING</replaceable></literal> part
+ stripped.
+ </para>
+ <para>
+ The matching is done as follows. If
+ <varname>LC_MESSAGES</varname> is of the form
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable>.<replaceable>ENCODING</replaceable>@<replaceable>MODIFIER</replaceable></literal>,
+ then it will match a key of the form
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable>@<replaceable>MODIFIER</replaceable></literal>.
+ If such a key does not exist, it will attempt to match
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable></literal>
+ followed by
+ <literal><replaceable>lang</replaceable>@<replaceable>MODIFIER</replaceable></literal>.
+ Then, a match against <replaceable>lang</replaceable> by itself
+ will be attempted. Finally, if no matching key is found the
+ required key without a locale specified is used. The encoding
+ from the <varname>LC_MESSAGES</varname> value is ignored
+ when matching.
+ </para>
+ <para>
+ If <varname>LC_MESSAGES</varname> does not have a <replaceable>MODIFIER</replaceable>
+ field, then no key with a modifier will be matched. Similarly, if
+ <varname>LC_MESSAGES</varname> does not have a <replaceable>COUNTRY</replaceable>
+ field, then no key with a country specified will be matched. If
+ <varname>LC_MESSAGES</varname> just has a <replaceable>lang</replaceable> field, then
+ it will do a straight match to a key with a similar value. The
+ following table lists possible matches of various <varname>LC_MESSAGES</varname> values in
+ the order in which they are matched. Note that the
+ <replaceable>ENCODING</replaceable> field isn't shown.
+ </para>
+ <table>
+ <title>Locale Matching</title>
+ <tgroup cols="2">
+<thead>
+ <row>
+ <entry><varname>LC_MESSAGES</varname> value</entry>
+ <entry>Possible keys in order of matching</entry>
+ </row>
+</thead>
+<tbody>
+ <row>
+ <entry><literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable>@<replaceable>MODIFIER</replaceable></literal></entry>
+ <entry>
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable>@<replaceable>MODIFIER</replaceable></literal>,
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable></literal>,
+ <literal><replaceable>lang</replaceable>@<replaceable>MODIFIER</replaceable></literal>,
+ <literal><replaceable>lang</replaceable></literal>,
+ default value
+ </entry>
+ </row>
+ <row>
+ <entry><literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable></literal></entry>
+ <entry>
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable></literal>,
+ <replaceable>lang</replaceable>,
+ default value
+ </entry>
+ </row>
+ <row>
+ <entry><literal><replaceable>lang</replaceable>@<replaceable>MODIFIER</replaceable></literal></entry>
+ <entry>
+ <literal><replaceable>lang</replaceable>@<replaceable>MODIFIER</replaceable></literal>,
+ <replaceable>lang</replaceable>,
+ default value
+ </entry>
+ </row>
+ <row>
+ <entry><replaceable>lang</replaceable></entry>
+ <entry>
+ <replaceable>lang</replaceable>,
+ default value
+ </entry>
+ </row>
+</tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ For example, if the current value of the <varname>LC_MESSAGES</varname> category
+ is <literal>sr_YU@Latn</literal> and the desktop file includes:
+ </para>
+ <programlisting>
+ Name=Foo
+ Name[sr_YU]=...
+ Name[sr@Latn]=...
+ Name[sr]=...</programlisting>
+ <para>
+ then the value of the <varname>Name</varname> keyed by <literal>sr_YU</literal> is used.
+ </para>
+ </sect1>
+ <sect1 id="recognized-keys">
+ <title>Recognized desktop entry keys</title>
+ <para>
+ Keys are either OPTIONAL or REQUIRED. If a key is OPTIONAL it may or
+ may not be present in the file. However, if it isn't, the
+ implementation of the standard should not blow up, it must provide
+ some sane defaults.
+ </para>
+ <para>
+ Some keys only make sense in the context when another particular key
+ is also present and set to a specific value. Those keys should not be
+ used if the particular key is not present or not set to the specific
+ value. For example, the <varname>Terminal</varname> key can only be used
+ when the value of the <varname>Type</varname> key is
+ <constant>Application</constant>.
+ </para>
+ <para>
+ If a REQUIRED key is only valid in the context of another key set to a
+ specific value, then it has to be present only if the other key is set to
+ the specific value. For example, the <varname>URL</varname> key has to be
+ present when and only when when the value of the <varname>Type</varname>
+ key is <constant>Link</constant>.
+ </para>
+ <para>
+ Some example keys: <varname>Name[C]</varname>, <varname>Comment[it]</varname>.
+ </para>
+ <table>
+ <title>Standard Keys</title>
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Description</entry>
+ <entry>Value Type</entry>
+ <entry>REQ?</entry>
+ <entry>Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry id="key-type"><varname>Type</varname></entry>
+ <entry>
+ This specification defines 3 types of desktop entries:
+ <constant>Application</constant> (type 1),
+ <constant>Link</constant> (type 2)
+ and <constant>Directory</constant> (type 3).
+ To allow the addition of new types in the future,
+ implementations should ignore desktop entries with an
+ unknown type.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry id="key-version"><varname>Version</varname></entry>
+ <entry>
+ Version of the Desktop Entry Specification that the
+ desktop entry conforms with. Entries that confirm with this
+ version of the specification should use <literal>1.0</literal>.
+ Note that the version field is not required to be present.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-name"><varname>Name</varname></entry>
+ <entry>
+ Specific name of the application, for example "Mozilla".
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-genericname"><varname>GenericName</varname></entry>
+ <entry>
+ Generic name of the application, for example "Web Browser".
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-nodisplay"><varname>NoDisplay</varname></entry>
+ <entry>
+ <varname>NoDisplay</varname> means "this application exists, but don't display it in the menus".
+ This can be useful to e.g. associate this application with MIME types, so that
+ it gets launched from a file manager (or other apps), without having a menu
+ entry for it (there are tons of good reasons for this, including e.g. the
+ <literal>netscape -remote</literal>, or <literal>kfmclient openURL</literal> kind of stuff).
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-comment"><varname>Comment</varname></entry>
+ <entry>
+ Tooltip for the entry, for example "View sites on the
+ Internet". The value should not be redundant with the values of
+ <varname>Name</varname> and <varname>GenericName</varname>.
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-icon"><varname>Icon</varname></entry>
+ <entry>
+ Icon to display in file manager, menus, etc. If the
+ name is an absolute path, the given file will be
+ used. If the name is not an absolute path, the algorithm described
+ in the <ulink
+ url="http://freedesktop.org/wiki/Standards/icon-theme-spec">Icon
+ Theme Specification</ulink> will be used to locate the icon.
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-hidden"><varname>Hidden</varname></entry>
+ <entry>
+ <varname>Hidden</varname> should have been called <varname>Deleted</varname>.
+ It means the user deleted (at his level)
+ something that was present (at an upper level, e.g. in the system dirs). It's
+ strictly equivalent to the <filename>.desktop</filename> file not existing at all, as far as that user is
+ concerned. This can also be used to "uninstall" existing files (e.g. due to a renaming)
+ - by letting <literal>make install</literal> install a file with <literal>Hidden=true</literal> in it.
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-onlyshowin"><varname>OnlyShowIn</varname>, <varname>NotShowIn</varname></entry>
+ <entry>
+ A list of strings identifying the environments that should
+ display/not display a given desktop entry. Only one of
+ these keys, either <varname>OnlyShowIn</varname> or
+ <varname>NotShowIn</varname>, may appear in a group (for
+ possible values see the <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+ Menu Specification</ulink>).
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>1-3</entry>
+ </row>
+ <row>
+ <entry id="key-tryexec"><varname>TryExec</varname></entry>
+ <entry>
+ Path to an executable file on disk used to determine if the program
+ is actually installed. If the path is not an absolute path, the file
+ is looked up in the $PATH environment variable. If the file is not
+ present or if it is not executable, the entry may be ignored (not be
+ used in menus, for example).
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-exec"><varname>Exec</varname></entry>
+ <entry>
+ Program to execute, possibly with arguments. See the <link
+ linkend="exec-variables"><varname>Exec</varname> key</link> for
+ details on how this key works.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-path"><varname>Path</varname></entry>
+ <entry>
+ If entry is of type <constant>Application</constant>, the working directory to run the program in.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-terminal"><varname>Terminal</varname></entry>
+ <entry>
+ Whether the program runs in a terminal window.
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-actions"><varname>Actions</varname></entry>
+ <entry>
+ Identifiers for application actions. This can be used to tell the
+ application to make a specific action, different from the default
+ behavior. The <link linkend="extra-actions">Application actions</link>
+ section describes how actions work.
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-mimetype"><varname>MimeType</varname></entry>
+ <entry>
+ The MIME type(s) supported by this application.
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-categories"><varname>Categories</varname></entry>
+ <entry>
+ Categories in which the entry should be shown in a menu (for
+ possible values see the <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+ Menu Specification</ulink>).
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-keywords"><varname>Keywords</varname></entry>
+ <entry>
+ A list of strings which may be used in addition to other
+ metadata to describe this entry. This can be useful e.g. to
+ facilitate searching through entries. The values are not meant
+ for display, and should not be redundant with the values of
+ <varname>Name</varname> or <varname>GenericName</varname>.
+ </entry>
+ <entry>localestring(s)</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-startupnotify"><varname>StartupNotify</varname></entry>
+ <entry>
+ If true, it is KNOWN that the application will send a "remove"
+ message when started with the DESKTOP_STARTUP_ID environment variable set.
+ If false, it is KNOWN that the application does not work
+ with startup notification at all (does not shown any window, breaks
+ even when using StartupWMClass, etc.).
+ If absent, a reasonable handling is up to implementations (assuming false,
+ using StartupWMClass, etc.). (See the <ulink url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup Notification Protocol Specification</ulink> for more details).
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-startupwmclass"><varname>StartupWMClass</varname></entry>
+ <entry>
+ If specified, it is known that the application will map at least one
+ window with the given string as its WM class or WM name hint (see the <ulink url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup Notification Protocol Specification</ulink> for more details).
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry id="key-url"><varname>URL</varname></entry>
+ <entry>
+ If entry is Link type, the URL to access.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ <entry>2</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+ <sect1 id="exec-variables">
+ <title>The <varname>Exec</varname> key</title>
+ <para>
+ The <varname>Exec</varname> key must contain a command line.
+ A command line consists of an executable program optionally followed
+ by one or more arguments.
+ The executable program can either be specified with its full path or
+ with the name of the executable only. If no full path is provided the
+ executable is looked up in the $PATH environment variable used by the
+ desktop environment.
+ The name or path of the executable program may not contain the equal
+ sign ("="). Arguments are separated by a space.
+ </para>
+ <para>
+ Arguments may be quoted in whole. If an argument contains a reserved
+ character the argument must be quoted. The rules for quoting of
+ arguments is also applicable to the executable name or path of the
+ executable program as provided.
+ </para>
+ <para>
+ Quoting must be done by enclosing the argument between double quotes
+ and escaping the double quote character, backtick character ("`"),
+ dollar sign ("$") and backslash character ("\") by preceding it with an
+ additional backslash character. Implementations must undo quoting before
+ expanding field codes and before passing the argument to the executable
+ program. Reserved characters are space (" "), tab, newline, double
+ quote, single quote ("'"), backslash character ("\"),
+ greater-than sign ("&gt;"), less-than sign ("&lt;"),
+ tilde ("~"), vertical bar ("|"), ampersand ("&amp;"), semicolon (";"),
+ dollar sign ("$"), asterisk ("*"), question mark ("?"), hash mark ("#"),
+ parenthesis ("(") and (")") and backtick character ("`").
+ </para>
+ <para>
+ Note that the general escape rule for values of type string states that
+ the backslash character can be escaped as ("\\") as well and that this
+ escape rule is applied before the quoting rule. As such, to
+ unambiguously represent a literal backslash character in a quoted
+ argument in a desktop entry file requires the use of four successive
+ backslash characters ("\\\\"). Likewise, a literal dollar sign in a
+ quoted argument in a desktop entry file is unambiguously represented
+ with ("\\$").
+ </para>
+ <para>
+ A number of special field codes have been defined which will be
+ expanded by the file manager or program launcher when encountered
+ in the command line.
+ Field codes consist of the percentage character ("%") followed by
+ an alpha character. Literal percentage characters must be escaped
+ as <literal>%%</literal>.
+ Deprecated field codes should be removed from the command line and
+ ignored.
+ Field codes are expanded only once, the string that is used to
+ replace the field code should not be checked for field codes itself.
+ </para>
+ <para>
+ Command lines that contain a field code that is not listed in this
+ specification are invalid and must not be processed, in particular
+ implementations may not introduce support for field codes not listed
+ in this specification. Extensions, if any, should be introduced by
+ means of a new key.
+ </para>
+ <para>
+ Implementations must take care not to expand field codes into multiple
+ arguments unless explicitly instructed by this specification.
+ This means that name fields, filenames and other replacements that
+ can contain spaces must be passed as a single argument
+ to the executable program after expansion.
+ </para>
+ <para>
+ Although the <varname>Exec</varname> key is defined to have a value
+ of the type string, which is limited to ASCII characters, field code
+ expansion may introduce non-ASCII characters in arguments.
+ Implementations must take care that all characters in arguments
+ passed to the executable program are properly encoded according to
+ the applicable locale setting.
+ </para>
+ <para>
+ Recognized field codes are as follows:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>%f</literal></entry>
+ <entry>
+ A single file name, even if multiple files are selected. The system
+ reading the desktop entry should recognize that the program in
+ question cannot handle multiple file arguments, and it should
+ should probably spawn and execute multiple copies of a program
+ for each selected file if the program is not able to handle
+ additional file arguments. If files are not on the local file system
+ (i.e. are on HTTP or FTP locations), the files will be copied to the local
+ file system and <literal>%f</literal> will be expanded to point at the temporary
+ file. Used for programs that do not understand the URL syntax.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%F</literal></entry>
+ <entry>
+ A list of files. Use for apps that can open several local
+ files at once.
+ Each file is passed as a separate argument to
+ the executable program.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%u</literal></entry>
+ <entry>
+ A single URL. Local files may either be passed as
+ file: URLs or as file path.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%U</literal></entry>
+ <entry>
+ A list of URLs.
+ Each URL is passed as a separate argument to
+ the executable program. Local files may either be passed as
+ file: URLs or as file path.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%d</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%D</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%n</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%N</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%i</literal></entry>
+ <entry>
+ The <varname>Icon</varname> key of the desktop entry
+ expanded as two arguments, first
+ <literal>--icon</literal> and then the value of the
+ <varname>Icon</varname> key. Should not expand to any
+ arguments if the <varname>Icon</varname> key is empty
+ or missing.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%c</literal></entry>
+ <entry>
+ The translated name of the application as listed in
+ the appropriate <varname>Name</varname> key in the
+ desktop entry.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%k</literal></entry>
+ <entry>
+ The location of the desktop file as either a URI (if for
+ example gotten from the vfolder system) or a local
+ filename or empty if no location is known.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%v</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%m</literal></entry>
+ <entry>
+ Deprecated.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ A command line may contain at most one %f, %u, %F or %U field code.
+ If the application should not open any
+ file the %f, %u, %F and %U field codes must be removed from the
+ command line and ignored.
+ </para>
+ <para>
+ Field codes must not be used inside a quoted argument, the result of
+ field code expansion inside a quoted argument is undefined. The %F and
+ %U field codes may only be used as an argument on their own.
+ </para>
+ </sect1>
+ <sect1 id="mime-types">
+ <title>Registering MIME Types</title>
+ <para>
+ The <varname>MimeType</varname> key is used to indicate the MIME
+ Types that an application knows how to handle. It is expected that
+ for some applications this list could become long. An application
+ is expected to be able to reasonably open files of these types
+ using the command listed in the <varname>Exec</varname> key.
+ </para>
+ <para>
+ There should be no priority for MIME Types in this field, or any
+ form of priority in the desktop file. Priority for applications
+ is handled external to the <filename>.desktop</filename> files.
+ </para>
+<!--
+ <sect2 id="mime-caching">
+ <title>Caching MIME Types</title>
+ <para>
+ To make parsing of all the desktop files less costly, a
+ <command>update-desktop-database</command> program is provided
+ that will generate a cache file. The concept is identical to
+ that of the 'update-mime-database' program in that it lets
+ applications avoid reading in (potentially) hundreds of files.
+ It will need to be run after every desktop file is installed.
+ One cache file is created for every directory in
+ $XDG_DATA_DIRS/applications/, and will create a file called
+ $XDG_DATA_DIRS/applications/mimeinfo.cache.
+ </para>
+ <para>
+ The format of the cache is similar to that of the desktop file,
+ and is just a list mapping mime-types to desktop files. Here's
+ a quick example of what it would look like:
+ </para>
+ <programlisting>application/x-foo=foo.desktop;bar.desktop;
+application/x-bar=bar.desktop;</programlisting>
+ <para>
+ Each MIME Type is listed only once per cache file, and the
+ desktop-id is expected to exist in that particular directory.
+ That is to say, if the cache file is located at
+ <filename>/usr/share/applications/mimeinfo.cache</filename>,
+ bar.desktop refers to the file
+ <filename>/usr/share/applications/bar.desktop</filename>.
+ </para>
+ </sect2>
+ <sect2 id="mime-priority">
+ <title>Priority of MIME Types and desktop files</title>
+ <para>
+ There is also a preference list to determine preferred
+ application of a given MIME Type. It defines the 'default'
+ application to handle a given MIME Type. It has the same format
+ as the cache list.
+ </para>
+ <programlisting>mime/type=desktop-id.desktop;</programlisting>
+ <para>
+ If a mime type is listed multiple times (either in the same
+ file, or in another file further down the search path), the
+ latter mention wins. If a listed file doesn't exist, or is
+ precluded through the <varname>OnlyShowIn</varname> or
+ <varname>NotShowIn</varname> keys, they should be ignored.
+ This means that applications will have to keep a history of the
+ preferred applications that they run into, so that if the top
+ desktop file for a given MIME Type isn't available, the second
+ one can be tested, etc.
+ </para>
+ <para>
+ It is also worth noting who this mechanism is defined for. It
+ is primarily intended for use by distributors/sysadmins to
+ provide a sane set of defaults for their users. Additionally,
+ users themselves can use this mechanism to override the user
+ defaults. We intentionally don't provide a way for application
+ authors themselves to list themselves as the default for a given
+ type, as we felt that that cannot work.
+ </para>
+ </sect2>
+-->
+ </sect1>
+ <sect1 id="extra-actions">
+ <title>Additional applications actions</title>
+ <para>
+ Desktop entries of type Application can include one or more actions. An
+ action represents an additional way to invoke the application.
+ Application launchers should expose them to the user (for example, as a
+ submenu) within the context of the application. This is used to build
+ so called "Quicklists" or "Jumplists".
+ </para>
+ <sect2 id="extra-actions-identifier">
+ <title>Action identifier</title>
+ <para>
+ Each action is identified by a string, following the same format
+ as key names (see <xref linkend="entries"/>). Each identifier is associated
+ with an action group that must be present in the <filename>.desktop</filename>
+ file. The action group is a group named <varname>Desktop Action %s</varname>,
+ where <varname>%s</varname> is the action identifier.
+ </para>
+ <para>
+ It is not valid to have an action group for an action identifier not
+ mentioned in the <varname>Actions</varname> key. Such an action group
+ must be ignored by implementors.
+ </para>
+ </sect2>
+ <sect2 id="extra-actions-keys">
+ <title>Action keys</title>
+ <para>
+ The following keys are supported within each action group. If a
+ REQUIRED key is not present in an action group, then the implementor
+ should ignore this action.
+ </para>
+ <table>
+ <title>Action Specific Keys</title>
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Description</entry>
+ <entry>Value Type</entry>
+ <entry>REQ?</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry id="key-action-group-name"><varname>Name</varname></entry>
+ <entry>
+ Label that will be shown to the user. Since actions are
+ always shown in the context of a specific application (that is, as
+ a submenu of a launcher), this only needs to be unambiguous within
+ one application and should not include the application name.
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-icon"><varname>Icon</varname></entry>
+ <entry>
+ Icon to be shown togheter with the action. If the name is
+ an absolute path, the given file will be used. If the name is not
+ an absolute path, the algorithm described in the <ulink
+ url="http://freedesktop.org/wiki/Standards/icon-theme-spec">Icon
+ Theme Specification</ulink> will be used to locate the icon.
+ Implementations may choose to ignore it.
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-osi-nsi">
+ <varname>OnlyShowIn</varname>, <varname>NotShowIn</varname>
+ </entry>
+ <entry>
+ A list of strings identifying the environments that should
+ display/not display this specific action. These keys are to be
+ interpreted in addition to the <varname>OnlyShowIn</varname>
+ and <varname>NotShowIn</varname> keys of the <varname>Desktop
+ Entry</varname> group, and are not replacing them. Only one of
+ these keys, either <varname>OnlyShowIn</varname> or
+ <varname>NotShowIn</varname>, may appear in each action group
+ (for possible values see the <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+ Menu Specification</ulink>).
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-exec"><varname>Exec</varname></entry>
+ <entry>
+ Program to execute for this action, possibly with arguments.
+ See the <link linkend="exec-variables"><varname>Exec</varname>
+ key</link> for details on how this key works.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+ <sect2 id="extra-actions-implementation-notes">
+ <title>Implementation notes</title>
+ <para>
+ Application actions should be supported by implementors. However, in
+ case they are not supported, implementors can simply ignore the
+ <varname>Actions</varname> key and the associated <varname>Desktop
+ Action</varname> action groups, and keep using the <varname>Desktop
+ Entry</varname> group: the primary way to describe and invoke the
+ application is through the Name, Icon and Exec keys from the
+ <varname>Desktop Entry</varname> group.
+ </para>
+ <para>
+ It is not expected that other desktop components showing application
+ lists (software installers, for instance) will provide any user
+ interface for these actions. Therefore applications must only include
+ actions that make sense as general launchers.
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="extending">
+ <title>Extending the format</title>
+ <para>
+ If the standard is to be amended with a new <literal>{key,value}</literal> pair which
+ should be applicable to all supporting parties, a group discussion
+ will take place. This is the preferred method for introducing
+ changes. If one particular party wishes to add a field for personal
+ use, they should prefix the key with the string <varname>X-<replaceable>PRODUCT</replaceable></varname>,
+ e.g. <varname>X-NewDesktop-Foo</varname>, following the precedent set by other IETF and RFC
+ standards.
+ </para>
+ <para>
+ Alternatively, fields can be placed in their own group, where they may
+ then have arbitrary key names. If this is the case, the group should
+ follow the scheme outlined above,
+ i.e. <literal>[X-<replaceable>PRODUCT</replaceable>
+ <replaceable>GROUPNAME</replaceable>]</literal> or
+ something similar. These steps will avoid namespace clashes between
+ different yet similar environments.
+ </para>
+ </sect1>
+ <appendix id="example">
+ <title>Example Desktop Entry File</title>
+ <programlisting>
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Foo Viewer
+Comment=The best viewer for Foo objects available!
+TryExec=fooview
+Exec=fooview %F
+Icon=fooview
+MimeType=image/x-foo;
+Actions=Gallery;Create;
+
+[Desktop Action Gallery]
+Exec=fooview --gallery
+Name=Browse Gallery
+
+[Desktop Action Create]
+Exec=fooview --create-new
+Name=Create a new Foo!
+Icon=fooview-new
+ </programlisting>
+ </appendix>
+ <appendix id="kde-items">
+ <title>Currently reserved for use within KDE</title>
+ <para>
+ For historical reasons KDE is using some KDE-specific extensions
+ that are currently not prefixed by a <literal>X-KDE-</literal> prefix.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ KDE specific keys: <varname>ServiceTypes</varname>,
+ <varname>DocPath</varname>, <varname>InitialPreference</varname>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ KDE specific types: <constant>ServiceType</constant>,
+ <constant>Service</constant> and <constant>FSDevice</constant>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ KDE also used the <varname>Keywords</varname> key before it was
+ standardized, using commas instead of semi-colons as separators.
+ At the time of standardization, the field had been prefixed with a
+ <literal>X-KDE</literal> prefix, but the Trinity fork still used
+ the non-prefixed variant.
+ </para>
+ <para>
+ KDE uses the following additional keys for desktop entries of the
+ <constant>FSDevice</constant> type.
+ </para>
+ <table>
+ <title>FSDevice Specific Keys</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Description</entry>
+ <entry>Value Type</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry id="key-dev"><varname>Dev</varname></entry>
+ <entry>
+ The device to mount.
+ </entry>
+ <entry>string</entry>
+ </row>
+ <row>
+ <entry id="key-fstype"><varname>FSType</varname></entry>
+ <entry>
+ The type of file system to try to mount.
+ </entry>
+ <entry>string</entry>
+ </row>
+ <row>
+ <entry id="key-mountpoint"><varname>MountPoint</varname></entry>
+ <entry>
+ The mount point of the device in question.
+ </entry>
+ <entry>string</entry>
+ </row>
+ <row>
+ <entry id="key-readonly"><varname>ReadOnly</varname></entry>
+ <entry>
+ Specifies whether or not the device is read only.
+ </entry>
+ <entry>boolean</entry>
+ </row>
+ <row>
+ <entry id="key-unmounticon"><varname>UnmountIcon</varname></entry>
+ <entry>
+ Icon to display when device is not mounted. Mounted devices display icon from the <varname>Icon</varname> key.
+ </entry>
+ <entry>localestring</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </appendix>
+ <appendix id="deprecated-items">
+ <title>Deprecated Items</title>
+ <para>
+ As this standard is quite old there are some deprecated items that
+ may or may not be used by several implementations.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>Type=MimeType</literal> is deprecated as there is a
+ new standard for this now, see the <ulink
+ url="http://www.freedesktop.org/Standards/shared-mime-info-spec">Shared
+ MIME-info Database specification</ulink> for more
+ information. In consequence the Keys
+ <varname>Patterns</varname> (various file name extensions
+ associated with the MIME type) and
+ <varname>DefaultApp</varname> (the default application
+ associated with this MIME type) are also deprecated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using <filename>.kdelnk</filename> instead of
+ <filename>.desktop</filename> as the file extension is
+ deprecated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using <literal>[KDE Desktop Entry]</literal> instead of
+ <literal>[Desktop Entry]</literal> as header is deprecated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>Encoding</literal> key is deprecated. It was used to
+ specify whether keys of type <literal>localestring</literal> were
+ encoded in UTF-8 or in the specified locale. Possible values are
+ <literal>UTF-8</literal> and <literal>Legacy-Mixed</literal>. See
+ <xref linkend="legacy-mixed"/> for more details.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Deprecated <varname>Exec</varname> field codes:
+ <literal>%m</literal> (the mini-icon associated with the
+ desktop entry, this should be expanded as two arguments,
+ <literal>--miniicon</literal> and the content of the
+ <varname>MiniIcon</varname> key, it can also be ignored by
+ expanding it to no arguments), %v (the device as listed
+ in the <varname>Dev</varname> key in the desktop file),
+ %d (the directory of a file), %D (the directories of
+ files), %n (the base name of a file) and %N (the base names
+ of files).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Deprecated keys: <varname>MiniIcon</varname> (small icon for
+ menus, etc.), <varname>TerminalOptions</varname> (if the
+ program runs in a terminal, any options that should be
+ passed to the terminal emulator before actually executing
+ the program), <varname>Protocols</varname>,
+ <varname>Extensions</varname>,
+ <varname>BinaryPattern</varname>,
+ <varname>MapNotify</varname>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>SwallowTitle</literal> and
+ <literal>SwallowExec</literal> keys are deprecated.
+ The <literal>SwallowTitle</literal> key is of type
+ <literal>localestring</literal> and specifies the title of the window
+ if is swallowed onto the panel. The <literal>SwallowExec</literal>
+ key is of type <literal>string</literal> and specifies the
+ program to exec if swallowed app is clicked.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>SortOrder</literal> key is deprecated. It is of type
+ <literal>string(s)</literal> and may be used to specify the order in
+ which to display files. The <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+ Menu Specification</ulink> defines another mechanism for defining the
+ order of menu items.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>FilePattern</literal> key is deprecated.
+ The value is a list of regular
+ expressions to match against for a file manager to determine if this
+ entry's icon should be displayed. Usually simply the name of the main
+ executable and friends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Historically some booleans have been represented by the numeric
+ entries <constant>0</constant> or <constant>1</constant>. With
+ this version of the standard they are now to be represented as a
+ boolean string. However, if an implementation is reading a pre-1.0
+ desktop entry, it should interpret <constant>0</constant> and
+ <constant>1</constant> as <constant>false</constant> and
+ <constant>true</constant>, respectively.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Historically lists have been comma separated. This is inconsistent with other lists which are separated by a semicolon. When reading a pre-1.0 desktop entry, comma separated lists should continue to be supported.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </appendix>
+ <appendix id="legacy-mixed">
+ <title>The <constant>Legacy-Mixed</constant> Encoding (Deprecated)</title>
+ <para>
+ The <constant>Legacy-Mixed</constant> encoding corresponds to the
+ traditional encoding of desktop files in older versions of the GNOME and
+ KDE desktop files. In this encoding, the encoding of each
+ <literal>localestring</literal> key is determined by the locale tag for
+ that key, if any, instead of being UTF-8. For keys without a locale tag,
+ the value must contain only ASCII characters.
+ </para>
+ <para>
+ If the file specifies an unsupported encoding, the implementation
+ should either ignore the file, or, if the user has requested a direct
+ operation on the file (such as opening it for editing), display an
+ appropriate error indication to the user.
+ </para>
+ <para>
+ In the absence of an <varname>Encoding</varname> key, the implementation may choose
+ to autodetect the encoding of the file by using such factors
+ as:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The location of the file on the file system
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Whether the contents of the file are valid UTF-8
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ If the implementation does not perform such auto-detection, it should
+ treat a file without an <varname>Encoding</varname> key in the same way as a file with an
+ unsupported <varname>Encoding</varname> key.
+ </para>
+ <para>
+ If the locale tag includes an <literal>.<replaceable>ENCODING</replaceable></literal> part, then that determines
+ the encoding for the line. Otherwise, the encoding is determined
+ by the language, or
+ <literal><replaceable>lang</replaceable>_<replaceable>COUNTRY</replaceable></literal>
+ pair from the locale tag, according to the following table.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Encoding</entry>
+ <entry>Aliases</entry>
+ <entry>Tags</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>ARMSCII-8 (*)</entry><entry></entry><entry>hy</entry>
+ </row><row>
+ <entry>BIG5</entry><entry></entry><entry>zh_TW</entry>
+ </row><row>
+ <entry>CP1251</entry><entry></entry><entry>be bg</entry>
+ </row><row>
+ <entry>EUC-CN</entry><entry>GB2312</entry><entry>zh_CN</entry>
+ </row><row>
+ <entry>EUC-JP</entry><entry></entry><entry>ja</entry>
+ </row><row>
+ <entry>EUC-KR</entry><entry></entry><entry>ko</entry>
+ </row><row>
+ <entry>GEORGIAN-ACADEMY (*)</entry><entry></entry><entry></entry>
+ </row><row>
+ <entry>GEORGIAN-PS (*)</entry><entry></entry><entry>ka</entry>
+ </row><row>
+ <entry>ISO-8859-1</entry><entry></entry><entry>br ca da de en es eu fi fr gl it nl no pt sv wa</entry>
+ </row><row>
+ <entry>ISO-8859-2</entry><entry></entry><entry>cs hr hu pl ro sk sl sq sr</entry>
+ </row><row>
+ <entry>ISO-8859-3 </entry><entry></entry><entry>eo</entry>
+ </row><row>
+ <entry>ISO-8859-5</entry><entry></entry><entry>mk sp</entry>
+ </row><row>
+ <entry>ISO-8859-7</entry><entry></entry><entry>el</entry>
+ </row><row>
+ <entry>ISO-8859-9</entry><entry></entry><entry>tr</entry>
+ </row><row>
+ <entry>ISO-8859-13</entry><entry></entry><entry>lt lv mi</entry>
+ </row><row>
+ <entry>ISO-8859-14</entry><entry></entry><entry>cy ga</entry>
+ </row><row>
+ <entry>ISO-8859-15</entry><entry></entry><entry>et</entry>
+ </row><row>
+ <entry>KOI8-R</entry><entry></entry><entry>ru</entry>
+ </row><row>
+ <entry>KOI8-U</entry><entry></entry><entry>uk</entry>
+ </row><row>
+ <entry>TCVN-5712 (*)</entry><entry>TCVN</entry><entry>vi</entry>
+ </row><row>
+ <entry>TIS-620</entry><entry></entry><entry>th</entry>
+ </row><row>
+ <entry>VISCII</entry><entry></entry><entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <variablelist>
+ <varlistentry>
+ <term>Encoding</term>
+ <listitem>
+ <para>
+ The name given here is listed here is typically the
+ canonical name for the encoding in the GNU C Library's
+ <function>iconv</function> facility. Encodings marked with (*) are not
+ currently supported by the GNU C Library; for this reason,
+ implementations may choose to ignore lines in desktop
+ files that resolve to this encoding. Desktop files with
+ these encodings are currently rare or non-existent.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Aliases</term>
+ <listitem>
+ <para>
+ Other names for the encoding found in existing desktop
+ files.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Tags</term>
+ <listitem>
+ <para>
+ Language tags for which this is the default encoding.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ This table above covers all tags and encodings that are known to
+ be currently in use. Implementors may choose to support
+ encodings not in the above set. For tags without defaults listed
+ in the above table, desktop file creators must specify the
+ <literal>.<replaceable>ENCODING</replaceable></literal> part of the locale tag.
+ </para>
+ <para>
+ Matching the <literal>.<replaceable>ENCODING</replaceable></literal> part of the locale tag against a locale
+ name or alias should be done by stripping all punctuation
+ characters from both the tag and the name or alias, converting
+ both name and alias to lowercase, and comparing the result.
+ This is necessary because, for example, <literal>Big5</literal> is frequently
+ found instead of <literal>BIG5</literal> and <literal>georgianacademy</literal> instead of
+ <literal>GEORGIAN-ACADEMY</literal>. Desktop files creators should, however, use
+ the name as it appears in the "Encoding" column above.
+ </para>
+ </appendix>
+</article>