summaryrefslogtreecommitdiffstats
path: root/desktop-entry/desktop-entry-spec.xml
diff options
context:
space:
mode:
authorlanius <lanius>2003-07-09 14:08:08 +0000
committerlanius <lanius>2003-07-09 14:08:08 +0000
commit4f78e6cdc2263594b6c185b7d86e95c7d518ca70 (patch)
treeb445a5534eb80e81f4d44acb5f7ae9bee9ee1da0 /desktop-entry/desktop-entry-spec.xml
parentefc3b89e6120b7c4ed6af06249c24d8576619083 (diff)
downloadxdg-specs-4f78e6cdc2263594b6c185b7d86e95c7d518ca70.tar.xz
sync with website / convert to xml
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
-rw-r--r--desktop-entry/desktop-entry-spec.xml1034
1 files changed, 1034 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..d39e891
--- /dev/null
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -0,0 +1,1034 @@
+<!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">
+ <artheader>
+ <title>Desktop Entry Standard</title>
+ <releaseinfo>Version 0.9.3</releaseinfo>
+ <date>13 March 2001</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>
+ </authorgroup>
+ </artheader>
+
+ <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>
+ These desktop entry files should have an extension of ".desktop" or
+ ".kdelnk". ".kdelnk" is deprecated, and is only maintained for
+ backwards compatibility. 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." Desktop entries which describe how
+ a directory is to be formatted/displayed should be simply called
+ ".directory".
+ </para>
+ <para>
+ The basic format of the desktop entry file requires that there be a
+ "group" header named "[Desktop Entry]". For backwards compatibility,
+ implementations may also support the header "[KDE Desktop Entry]".
+ This "group" entry denotes that all {key,value} pairs following it
+ belong in the Desktop Entry group. There may be other groups present
+ in the file (see MIME types discussion below), 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 proceeding this group in the
+ desktop entry file but possibly one or more comments (see
+ below).
+ </para>
+ <para>
+ Group headers may not contain the characters '[' and ']' as
+ those delimit the header.
+ </para>
+ <para>
+ Lines beginning with a "#" are considered comments and will be
+ ignored, however they should be preserved across reads / writes of the
+ desktop entry 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>
+ <para>
+ Entries in the file are {key,value} pairs in the format:
+ </para>
+ <programlisting>
+Name=Value</programlisting>
+ <para>
+ Space before and after the equals sign should be ignored; the "="
+ sign is the actual delimiter.
+ </para>
+ <para>
+ The escape sequences \s, \n, \t, \r, and \\ are supported,
+ meaning ASCII space, newline, tab, carriage return, and
+ backslash, respectively.
+ </para>
+ </sect1>
+ <sect1 id="value-types">
+ <title>Possible value types</title>
+ <para>
+ The value types recognized are string, localestring, regular expression,
+ boolean (encoded as the string true/false), and numeric.
+ </para>
+ <para>
+ The difference between string and localestring is that the value for
+ a string key must contain only UTF-8 characters and while the value
+ of a localestring key may contain localized encodings. (See
+ section 5.)
+ </para>
+ <para>
+ Some keys can have multiple values; these should be separated by a
+ semicolon. Those keys which have several values should have a
+ semicolon as the trailing character. For lists of strings,
+ semicolons are simply not allowed in the strings, there is no
+ escape mechanism.
+ </para>
+ </sect1>
+ <sect1 id="recognized-keys">
+ <title>Recognized desktop entry keys</title>
+ <para>
+ Keys 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 lang[_COUNTRY][.ENCODING],
+ where either _COUNTRY or .ENCODING 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 LC_MESSAGES
+ category against the <replaceable>locale</replaceable> postfixes of all occurrences of the key,
+ with the .ENCODING part stripped. (The .ENCODING is used when the
+ Encoding key for the desktop entry file is Legacy-Mixed, see
+ <xref linkend="legacy-mixed"/>.)
+ </para>
+ <para>
+ The matching is done as follows: if the current value of
+ LC_MESSAGES is
+ <replaceable>lang</replaceable>_<replaceable>country</replaceable>.<replaceable>encoding</replaceable>@<replaceable>modifier</replaceable>,
+ then, if a key for
+ <replaceable>lang</replaceable>_<replaceable>country</replaceable>
+ is present, it will be used. Otherwise, if a key for
+ <replaceable>lang</replaceable> is present, it will be used. If
+ both of these are missing, the required key without a locale
+ specified is used. The encoding and modifier from the
+ LC_MESSAGES value are ignored.
+ </para>
+ <para>
+ For example, if the current value of the LC_MESSAGES category
+ is de_DE, and the desktop file includes:
+ </para>
+ <programlisting>
+ Name=Foo
+ Name[de]=Foo auf Deutsch</programlisting>
+ <para>
+ Then the value used for the name key will be 'Foo auf Deutsch'. However,
+ if a value is specified for Name[de_DE], then that will be used
+ instead.
+ </para>
+ <para>
+ Case is significant. The keys "Name" and "NAME" are not equivalent.
+ The same holds for group names. Key values are case sensitive as
+ well.
+ </para>
+ <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. Additionally, keys either MUST or MAY be
+ supported by a particular implementation.
+ </para>
+ <para>
+ Some keys only make sense in the context when another particular key
+ is also present.
+ </para>
+ <para>
+ Some example keys: Name[C], Comment[it].
+ </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>MUST?</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Encoding</entry>
+ <entry>
+ encoding of the desktop entry file
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Version</entry>
+ <entry>
+ version of Desktop Entry Specification
+ </entry>
+ <entry>numeric (4)</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Name</entry>
+ <entry>
+ specific name of the application, for example "Mozilla"
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>GenericName</entry>
+ <entry>
+ generic name of the application, for example "Web Browser"
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Type</entry>
+ <entry>
+ the type of desktop entry
+ </entry>
+ <entry>string (1)</entry>
+ <entry>YES</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>FilePattern</entry>
+ <entry>
+ 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.
+ </entry>
+ <entry>regexp(s)</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>TryExec</entry>
+ <entry>
+ filename of a binary on disk used to determine if the
+ program is actually installed. If not, entry may not
+ show in menus, etc.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>NoDisplay</entry>
+ <entry>
+ whether not to display in menus, etc.
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Comment</entry>
+ <entry>
+ tooltip for the entry, for example "View sites on the
+ Internet"; should not be redundant with Name or
+ GenericName.
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Exec</entry>
+ <entry>
+ program to execute, possibly with arguments
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Actions</entry>
+ <entry>
+ additional actions possible, see MIME type discussion
+ in <xref linkend="mime-types"/>
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Icon</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, an
+ implementation-dependent search algorithm will be used
+ to locate the icon. Icons may be localized with the
+ Icon[xx]= syntax, but filenames should be in UTF-8, not
+ locale encoding.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>MiniIcon</entry>
+ <entry>
+ small icon for menus, etc (deprecated).
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Hidden</entry>
+ <entry>
+ if true, pretend this entry doesn't exist.
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Path</entry>
+ <entry>
+ if entry is type Application, the working directory to run the program in.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>Terminal</entry>
+ <entry>
+ whether the program runs in a terminal window
+ </entry>
+ <entry>boolean (2)</entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>TerminalOptions</entry>
+ <entry>
+ if the program runs in a terminal, any options that
+ should be passed to the terminal emulator before
+ actually executing the program. This field is
+ deprecated because it's dependent on which emulator
+ is used.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>SwallowTitle</entry>
+ <entry>
+ if entry is swallowed onto the panel, this should be the title of window
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>SwallowExec</entry>
+ <entry>
+ program to exec if swallowed app is clicked
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>MimeType</entry>
+ <entry>
+ the MIME type(s) supported by this entry
+ </entry>
+ <entry>regexp(s)</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Patterns</entry>
+ <entry>
+ if entry is type MimeType, various file name extensions
+ associated with the MIME type.
+ </entry>
+ <entry>regexp(s)</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>DefaultApp</entry>
+ <entry>
+ if entry is type MimeType, the default application associated with this mime type
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Dev</entry>
+ <entry>
+ if FSDevice type of entry, the device to mount
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>FSType</entry>
+ <entry>
+ The type of filesystem to try to mount
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>MountPoint</entry>
+ <entry>
+ if FSDevice type of entry, the mount point of the device in question
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>ReadOnly</entry>
+ <entry>
+ if FSDevice type of entry, specifies whether or not the device is read-only
+ </entry>
+ <entry>boolean (2)</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>UnmountIcon</entry>
+ <entry>
+ icon to display when device is not mounted Mounted devices display icon from Icon key
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>SortOrder</entry>
+ <entry>
+ if entry of type Directory, this may specify the order in which to display files
+ </entry>
+ <entry>strings (3)</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>URL</entry>
+ <entry>
+ if entry is Link type, the URL to access
+ </entry>
+ <entry>string </entry>
+ <entry>NO</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry>BinaryPattern</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>DocPath</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Extensions</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>InitialPreference</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Keywords</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>MapNotify</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>Protocols</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry>ServiceTypes</entry>
+ <entry>
+ Deprecated.
+ </entry>
+ <entry>string</entry>
+ <entry>NO</entry>
+ <entry>NO</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Notes:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ possible values are Application, Link, FSDevice, MimeType, Directory,
+ Service, ServiceType
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ historically these have been represented by the numeric entries 0
+ or 1. 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 0 and 1 as false
+ and true, respectively.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ historically this has been a comma separated list. 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>
+ <listitem>
+ <para>
+ while the version field is not required to be present, it should
+ be in all newer implementations of the Desktop Entry specification.
+ If the version number is not present, a "pre-standard" desktop entry
+ file is to be assumed.
+ </para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+ <sect1 id="character-encoding">
+ <title>Character set encoding of the file</title>
+ <para>
+ Desktop entry files are encoded as lines of 8-bit characters separated
+ by LF characters.
+ </para>
+ <para>
+ Except for comments and values of type localestring, only ASCII
+ characters are permitted in the file:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Key names must contain only the characters 'A-Za-z0-9-'
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Group names may contain all ASCII characters except for control
+ characters and '[' and ']'.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Values of type string may contain all ASCII characters except
+ for control characters.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Values of type boolean must either be the string 'true' or
+ 'false'
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Numeric values must be a valid floating point number as recognized
+ by the %f specifier for scanf.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <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>
+ <para>
+ The encoding for values of type localestring is determined by the
+ Encoding field of the desktop entry. This field should always
+ be present. (However, many legacy files may not include it.)
+ </para>
+ <para>
+ Only two values for Encoding are currently defined: 'UTF-8', and
+ 'Legacy-Mixed', and desktop files must not use any other value.
+ Implementations must support the UTF-8 encoding, and may choose
+ to support Legacy-Mixed in addition. For this reason, authors
+ of desktop files are encouraged to use the value 'UTF-8'.
+ </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 Encoding line, 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 filesystem
+ </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 Encoding key in the same way as a file with an
+ unsupported Encoding Key.
+ </para>
+ </sect1>
+ <sect1 id="exec-variables">
+ <title>List of valid Exec parameter variables</title>
+ <para>
+ Each "Exec" field may take a number of arguments which will be
+ expanded by the file manager or program launcher and passed to the
+ program if necessary.
+ </para>
+ <para>
+ Literal % characters must be escaped as %%, and adding new
+ format characters is not allowed. It's a fatal error to have an
+ Exec field with a format character not given in the spec.
+ Again for emphasis: <emphasis>nonstandard extensions are
+ not allowed here - you must add an X-Foo-Exec field if you have
+ nonstandard Exec lines</emphasis>.
+ </para>
+ <para>
+ Recognized fields are as follows:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>%f</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. HTTP or FTP locations), the files will be copied to the local
+ file system and %f will be expanded to point at the temporary
+ file. Used for programs that do not understand URL syntax.
+ </entry>
+ </row>
+ <row>
+ <entry>%F</entry>
+ <entry>
+ a list of files. Use for apps that can open several local
+ files at once.
+ </entry>
+ </row>
+ <row>
+ <entry>%u</entry>
+ <entry>
+ a single URL.
+ </entry>
+ </row>
+ <row>
+ <entry>%U</entry>
+ <entry>
+ a list of URLs.
+ </entry>
+ </row>
+ <row>
+ <entry>%d</entry>
+ <entry>
+ directory containing the file that would be passed in a %f field
+ </entry>
+ </row>
+ <row>
+ <entry>%D</entry>
+ <entry>
+ list of directories containing the files that would be
+ passed in to a %F field
+ </entry>
+ </row>
+ <row>
+ <entry>%n</entry>
+ <entry>
+ a single filename (without path)
+ </entry>
+ </row>
+ <row>
+ <entry>%N</entry>
+ <entry>
+ a list of filenames (without path)
+ </entry>
+ </row>
+ <row>
+ <entry>%i</entry>
+ <entry>
+ the icon associated with the desktop entry
+ </entry>
+ </row>
+ <row>
+ <entry>%m</entry>
+ <entry>
+ the mini-icon associated with the desktop entry
+ </entry>
+ </row>
+ <row>
+ <entry>%c</entry>
+ <entry>
+ the comment associated with the desktop entry
+ </entry>
+ </row>
+ <row>
+ <entry>%k</entry>
+ <entry>
+ the name of the desktop file
+ </entry>
+ </row>
+ <row>
+ <entry>%v</entry>
+ <entry>
+ the name of the Device entry in the desktop file
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect1>
+ <sect1 id="mime-types">
+ <title>Detailed discussion of supporting MIME types</title>
+ <para>
+ It is in every desktop's best interest to have thorough support for
+ mime types. The old /etc/mailcap and /etc/mime.types files are rather
+ limited in scope and frankly, are outdated. Various desktop systems
+ have come up with different ways of extending this original system,
+ but none are compatible with each other. The Desktop Entry Standard
+ hopes to be able to provide the beginnings of a solution to this
+ problem.
+ </para>
+ <para>
+ At a very basic level, the "Exec" key provides the default action to
+ take when the program described by a desktop entry is used to open a
+ document or data file. Usually this consists of some action along the
+ lines of "kedit %f" or "ee %f". This is a good
+ start, but it isn't as flexible as it can be.
+ </para>
+ <para>
+ Let us first establish that a program which supports a MIME type or
+ multiple mime types may be able to support multiple actions on those
+ MIME types as well. The desktop entry may want to define additional
+ actions in addition to the default. The toplevel "Exec" key describes
+ the default action; Let us define this action to also be known as the
+ "Open" action. Additional actions which might be possible include
+ View, Edit, Play, etc. A further revision of this document will
+ probably specify several "standard" actions in addition to the default
+ "Open" action, but in all cases, the number of actions is
+ arbitrary.
+ </para>
+ <para>
+ Let us use a sound player as a simple example. Call it sp. The
+ default Exec (Open) action for this program would likely look
+ something like:
+ </para>
+ <programlisting>
+Exec=sp %u</programlisting>
+ <para>
+ However, imagine the sound player also supports editing of sound files
+ in a graphical manner. We might wish to define an additional action
+ which could accomodate this. Adding the action would be performed
+ like this:
+ </para>
+ <programlisting>
+Actions=Edit;
+
+[Desktop Action Edit]
+Exec=sp -edit %u</programlisting>
+ <para>
+ As you can see, defining the action "edit" will enable an additional
+ group of the name [Desktop Action <replaceable>actionname</replaceable>] to be read. This
+ group can contain an additional Exec line, as well as possibly other
+ information like a new Name, Comment, Icon, and Path. Thus
+ right-clicking on a .wav file will show both the default "Open" action
+ and this "Edit" action to both be displayed as choices in the
+ context-menu. A left click (double or single, whichever the file
+ manager implements) would cause the default action to take place.
+ These are implementation-specific details which are up to the
+ implementer, and are not enforced by this standard.
+ </para>
+ <para>
+ If no DefaultApp is specified for a particular MIME type, any one of
+ the programs registered which claim to be able to handle the MIME type
+ may become the default handler. This behaviour is undefined and
+ implementation-specific. KDE doesn't use a DefaultApp anymore, but assigns
+ a Preference number to each program, so that the highest number is the
+ one chosen for handling the MIME type.
+ </para>
+ </sect1>
+ <sect1 id="extending">
+ <title>Extending the format</title>
+ <para>
+ If the standard is to be amended with a new {key,value} 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 "X-PRODUCT",
+ i.e. "X-NewDesktop-Foo", 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. [X-PRODUCT GROUPNAME] 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
+Actions=Edit;Inverse
+Icon=fooview.png
+MimeType=image/x-foo
+X-KDE-Library=libfooview
+X-KDE-FactoryName=fooviewfactory
+X-KDE-ServiceType=FooService
+
+[Desktop Action Inverse]
+Exec=fooview --inverse %f
+Name=Foo Viewer (inverse image)
+
+[Desktop Action Edit]
+Exec=fooview --edit %f
+Name=Foo Viewer (edit image)
+Icon=fooview-edit.png</programlisting>
+ </appendix>
+ <appendix id="legacy-mixed">
+ <title>The Legacy-Mixed encoding</title>
+ <para>
+ The Legacy-Mixed 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 localestring key
+ is determined by the locale tag for that key, if any. For keys
+ without a locale tag, the value must contain only ASCII
+ characters.
+ </para>
+ <para>
+ If the locale tag includes an .ENCODING part, then that determines
+ the encoding for the line. Otherwise, the encoding is determined
+ by the language, or language-country pair from the locale tag, according
+ to the following table. (A language-country locale tag matches a
+ language by itself in the table if the language-country pair isn't
+ explicitely in the 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 wa no pt sv</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>ga cy</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
+ iconv 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
+ ENCODING part of the locale tag.
+ </para>
+ <para>
+ Matching the ENCODING 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, "Big5" is frequently
+ found instead of "BIG5" and "georgianacademy" instead of
+ GEORGIAN-ACADEMY. Desktop files creators should, however, use
+ the name as it appears in the "Encoding" column above.
+ </para>
+ </appendix>
+</article>
+