It was pointed out in
http://lists.freedesktop.org/archives/xdg/2006-April/008012.html
that the Exec key in .desktop files isn't very well documented.
I have attached a patch that is supposed to clarify this. I am aware
that current implementations may allow you to put slightly more fancy
shell constructs in an Exec field, I wanted to capture the basic
guaranteed functionality here without having to include the bash/ksh/tsh
manpage. In particular I do NOT want to introduce any requirements that
are not met by existing implementations.
Your review, feedback as well as translation into english are highly
appreciated.
The current version of the spec is 0.9.5 and can be found at
http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-0
.9.5.html
The patch is against the XML version of 0.9.5 which is available at
http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-0
.9.5.xml
Process safeguard: The review period for this patch ends at Tuesday Aug
15. Without substantial opposition/requests for change I will commit the
patch after the end of the review period.
Description of the patch:
* Consistent use of "Key" (e.g. the "Exec" key), "argument" (the things
that eventually get passed on the command line to the executable) and
"field code" (e.g. "%f")
* Clarify that %F, %U, %D and %N must/will expand to multiple arguments
* Re-added %m to the table because it must be processed according to the
instructions for deprecated field codes.
* Change wording of the Exec section as follows
CURRENT:
List of valid Exec parameter variables
======================================
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.
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 (exception to this are the
deprecated format characters which can be ignored, that is expanded to
no parameters, by the implementation). Again for emphasis: nonstandard
extensions are not allowed here - you must add an X-Foo-Exec field if
you have nonstandard Exec lines.
The escaping of the exec parameters is done in the way the mailcap
specification describes. Take a look at RFC 1524 for more information.
====
PROPOSED:
The Exec key
============
The Exec 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 used by the desktop environment.
Arguments are separated by a space. A space can be included into an
argument by enclosing the whole argument with either single or double
quotes.
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 %%.
Command lines that contain a field code that is not listed in this
specification are invalid. 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.
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.
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.
====
Waldo Bastian
Linux Client Architect - Client Linux Foundation Technology
Channel Platform Solutions Group
Intel Corporation - http://www.intel.com/go/linux
OSDL DTL Tech Board Chairman
Index: desktop-entry-spec.xml
===================================================================
RCS file: /cvs/menus/desktop-entry-spec/desktop-entry-spec.xml,v
retrieving revision 1.10
diff -u -r1.10 desktop-entry-spec.xml
--- desktop-entry-spec.xml 28 May 2006 23:53:11 -0000 1.10
+++ desktop-entry-spec.xml 7 Aug 2006 23:48:48 -0000
@@ -4,8 +4,8 @@
<article id="index">
<articleinfo>
<title>Desktop Entry Specification</title>
- <releaseinfo>Version 0.9.5</releaseinfo>
- <date>28 May 2006</date>
+ <releaseinfo>Version 0.9.6</releaseinfo>
+ <date>7 Aug 2006</date>
<authorgroup>
<author>
<firstname>Preston</firstname>
@@ -43,6 +43,15 @@
</address>
</affiliation>
</author>
+ <author>
+ <firstname>Waldo</firstname>
+ <surname>Bastian</surname>
+ <affiliation>
+ <address>
+ <email>[EMAIL PROTECTED]</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
</articleinfo>
@@ -635,33 +644,58 @@
</table>
</sect1>
<sect1 id="exec-variables">
- <title>List of valid <varname>Exec</varname> parameter variables</title>
- <para>
- Each <varname>Exec</varname> 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>
+ <title>The <varname>Exec</varname> key</title>
<para>
- Literal <literal>%</literal> characters must be escaped as <literal>%%</literal>, and adding new
- format characters is not allowed. It's a fatal error to have an
- <varname>Exec</varname> field with a format character not given in the spec (exception
- to this are the deprecated format characters which can be ignored,
- that is expanded to no parameters, by the implementation).
- Again for emphasis: <emphasis>nonstandard extensions are
- not allowed here - you must add an <varname>X-Foo-Exec</varname> field if you have
- nonstandard <varname>Exec</varname> lines</emphasis>.
+ 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 used by the desktop environment.
+ Arguments are separated by a space.
+ A space can be included into an argument by enclosing the whole
+ argument with either single or double quotes.
+ </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>.
+ Command lines that contain a field code that is not listed
+ in this specification are invalid.
+ 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>
+ 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>
- The escaping of the exec parameters is done in the way the mailcap
- specification describes. Take a look at
- <ulink url="http://www.ietf.org/rfc/rfc1524";>RFC 1524</ulink>
- for more information.
- </para>
<para>
- Recognized fields are as follows:
+ 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>
@@ -682,6 +716,8 @@
<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>
@@ -694,6 +730,8 @@
<entry><literal>%U</literal></entry>
<entry>
A list of URLs.
+ Each URL is passed as a separate argument to
+ the executable program.
</entry>
</row>
<row>
@@ -707,6 +745,8 @@
<entry>
List of directories containing the files that would be
passed in to a <literal>%F</literal> field.
+ Each directory is passed as a separate argument to
+ the executable program.
</entry>
</row>
<row>
@@ -719,23 +759,27 @@
<entry><literal>%N</literal></entry>
<entry>
A list of filenames (without paths).
+ Each filename is passed as a separate argument to
+ the executable program.
</entry>
</row>
<row>
<entry><literal>%i</literal></entry>
<entry>
- The <varname>Icon</varname> field of the desktop entry
- expanded as two parameters, first
- <literal>--icon</literal> and then the contents of the
- <varname>Icon</varname> field. Should not expand as any
- parameters if the <varname>Icon</varname> field is empty
+ 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 <varname>Name</varname> field associated with the desktop entry.
+ The translated name of the application as listed in
+ the appropriate <varname>Name</varname> key in the
+ desktop entry.
</entry>
</row>
<row>
@@ -749,7 +793,14 @@
<row>
<entry><literal>%v</literal></entry>
<entry>
- The name of the <varname>Device</varname> entry in the desktop file.
+ The device as listed in the <varname>Dev</varname> key in
+ the desktop file.
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%m</literal></entry>
+ <entry>
+ Deprecated.
</entry>
</row>
</tbody>
@@ -765,7 +816,7 @@
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.
+ 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
@@ -815,7 +866,7 @@
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.
+ <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
@@ -944,12 +995,12 @@
</listitem>
<listitem>
<para>
- Deprecated <varname>Exec</varname> parameters:
+ Deprecated <varname>Exec</varname> field codes:
<literal>%m</literal> (the mini-icon associated with the
- desktop entry, this should be expanded as two parameters,
+ desktop entry, this should be expanded as two arguments,
<literal>--miniicon</literal> and the content of the
- <varname>MiniIcon</varname> field, it can also be ignored by
- expanding it to no parameters).
+ <varname>MiniIcon</varname> key, it can also be ignored by
+ expanding it to no arguments).
</para>
</listitem>
<listitem>
@@ -1010,7 +1061,7 @@
appropriate error indication to the user.
</para>
<para>
- In the absence of an <varname>Encoding</varname> line, the implementation may choose
+ 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>
@@ -1029,7 +1080,7 @@
<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.
+ unsupported <varname>Encoding</varname> key.
</para>
<para>
If the locale tag includes an <literal>.<replaceable>ENCODING</replaceable></literal> part, then that determines
_______________________________________________
xdg mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/xdg
