summaryrefslogtreecommitdiffstats
path: root/desktop-entry/desktop-entry-spec.xml
diff options
context:
space:
mode:
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
-rw-r--r--desktop-entry/desktop-entry-spec.xml184
1 files changed, 93 insertions, 91 deletions
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index 1d5716a..c890a57 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -61,16 +61,15 @@
should be simply called <filename>.directory</filename>.
</para>
<para>
- The basic format of the desktop entry file requires that there be a
- "group" header named <literal>[Desktop Entry]</literal>.
- This "group" entry denotes that all
- <literal>{key,value}</literal> 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
+ The basic format of the desktop entry file requires that there be
+ a "group" header named <literal>[Desktop Entry]</literal>. This
+ "group" entry denotes that all <literal>{key,value}</literal>
+ pairs following it belong in the Desktop Entry group. 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 proceeding this group in
+ the desktop entry file but possibly one or more comments (see
below).
</para>
<para>
@@ -92,18 +91,16 @@
<para>
Entries in the file are <literal>{key,value}</literal> pairs in the format:
</para>
- <programlisting>
-Name=Value</programlisting>
+ <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>
- The escape sequences <literal>\s</literal>,
- <literal>\n</literal>, <literal>\t</literal>,
- <literal>\r</literal>, and <literal>\\</literal> are supported,
- meaning ASCII space, newline, tab, carriage return, and
- backslash, respectively.
+ The escape sequences <literal>\s</literal>, <literal>\n</literal>,
+ <literal>\t</literal>, <literal>\r</literal>, and
+ <literal>\\</literal> are supported, meaning ASCII space, newline,
+ tab, carriage return, and backslash, respectively.
</para>
</sect1>
<sect1 id="value-types">
@@ -113,16 +110,17 @@ Name=Value</programlisting>
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 ASCII characters while the value
- of a localestring key may contain UTF-8 characters.
+ Values of type <literal>string</literal> must contain only ASCII
+ characters excluding control characters. Values of type
+ <literal>localestring</literal> are user displayable, and are
+ encoded in UTF-8 unless the <constant>Legacy-Mixed</constant>
+ Encoding is specified (see <xref linkend="legacy-mixed"/>.)
</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.
+ semicolon as the trailing character. Semicolons in these values
+ need to be escaped using <literal>\;</literal>.
</para>
</sect1>
<sect1 id="recognized-keys">
@@ -372,7 +370,7 @@ Name=Value</programlisting>
<entry>1-4</entry>
</row>
<row>
- <entry id="key-hidden">Hidden</entry>
+ <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)
@@ -476,7 +474,7 @@ Name=Value</programlisting>
<entry>
The MIME type(s) supported by this entry.
</entry>
- <entry>regexp(s)</entry>
+ <entry>strings(s)</entry>
<entry>NO</entry>
<entry>NO</entry>
<entry>1</entry>
@@ -778,76 +776,80 @@ Name=Value</programlisting>
</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 <filename>/etc/mailcap</filename> and
- <filename>/etc/mime.types</filename> 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 Specification
- hopes to be able to provide the beginnings of a solution to this
- problem.
- </para>
- <para>
- At a very basic level, the <varname>Exec</varname> 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 <literal>kedit %f</literal> or <literal>ee %f</literal>. 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 top level <varname>Exec</varname> 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 <literal>sp</literal>. The
- default <varname>Exec</varname> (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 accommodate this. Adding the action would be performed
- like this:
- </para>
- <programlisting>
-Actions=Edit;
-
-[Desktop Action Edit]
-Exec=sp -edit %u</programlisting>
+ <title>Registering MIME Types</title>
<para>
- As you can see, defining the action "Edit" will enable an additional
- group of the name <literal>[Desktop Action <replaceable>actionname</replaceable>]</literal> to be read. This
- group can contain an additional <varname>Exec</varname> line, as well as possibly other
- information like a new <varname>Name</varname>,
- <varname>Comment</varname>, <varname>Icon</varname>, and
- <varname>Path</varname>. 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.
+ The <varname>MimeType</varname> key is used to indicate the MIME
+ Types that an application knows how to handle. Applications that
+ can handle multiple MIME Types would list all of the ones it can
+ handle in a ';' separated list, as normal. 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> keyword.
</para>
<para>
- If no <varname>DefaultApp</varname> 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 <varname>DefaultApp</varname> anymore, but assigns
- a preference number to each program, so that the highest number is the
- one chosen for handling the MIME type.
+ 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> files, 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="extending">
<title>Extending the format</title>