diff options
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
| -rw-r--r-- | desktop-entry/desktop-entry-spec.xml | 1392 |
1 files changed, 1392 insertions, 0 deletions
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 (">"), less-than sign ("<"), + tilde ("~"), vertical bar ("|"), ampersand ("&"), 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> |