[Portland] PATCH: Desktop entry spec - Exec key

[Bastian, Waldo]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: desktop_entry_exec.diff
Type: text/x-diff
Size: 9975 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/portland/attachments/20060807/c2eccdaa/desktop_entry_exec-0001.bin