From af1b346daa90b9cb88ec9e3b6d3ebd05942a73d7 Mon Sep 17 00:00:00 2001 From: Waldo Bastian Date: Tue, 22 Aug 2006 18:59:19 +0000 Subject: clarification of Exec key correction of StartupWMClass, clarify * clarification of Exec key * correction of StartupWMClass, clarify StartupNotify (Lubos Lunak) * deprecate SortOrder and FilePattern key (Vincent Untz) * remove section on "MIME Type caching" from spec (Vincent Untz) * groups and keys must be unique (Vincent Untz) See http://lists.freedesktop.org/archives/xdg/2006-August/008446.html --- desktop-entry/ChangeLog | 8 ++ desktop-entry/desktop-entry-spec.xml | 227 ++++++++++++++++++++++++----------- 2 files changed, 167 insertions(+), 68 deletions(-) diff --git a/desktop-entry/ChangeLog b/desktop-entry/ChangeLog index 7fa8c3c..67470de 100644 --- a/desktop-entry/ChangeLog +++ b/desktop-entry/ChangeLog @@ -1,3 +1,11 @@ +2006-08-22 Waldo Bastian + * clarification of Exec key + * correction of StartupWMClass, clarify StartupNotify (Lubos Lunak) + * deprecate SortOrder and FilePattern key (Vincent Untz) + * remove section on "MIME Type caching" from spec (Vincent Untz) + * groups and keys must be unique (Vincent Untz) + See http://lists.freedesktop.org/archives/xdg/2006-August/008446.html + 2006-05-28 Vincent Untz * cleanup of text and some reorg for clearity * move all of the legacy-mixed encoding stuff to the appendix diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml index 46db5ed..1dd65f0 100644 --- a/desktop-entry/desktop-entry-spec.xml +++ b/desktop-entry/desktop-entry-spec.xml @@ -4,8 +4,8 @@
Desktop Entry Specification - Version 0.9.5 - 28 May 2006 + Version 0.9.6 + 7 Aug 2006 Preston @@ -43,6 +43,15 @@ + + Waldo + Bastian + +
+ waldo.bastian@intel.com +
+ + @@ -104,6 +113,9 @@ Group names may contain all ASCII characters except for [ and ] and control characters. + + Multiple groups may not have the same name. + All {key,value} pairs following a group header until a new group header belong to the group. @@ -130,12 +142,17 @@ = sign is the actual delimiter. - Key names must contain only the characters A-Za-z0-9- + Key names must contain only the characters + A-Za-z0-9-. As the case is significant, the keys Name and NAME are not equivalent. + + Multiple keys in the same group may not have the same name. Keys in + different groups may have the same name. + @@ -448,19 +465,6 @@ NO 1-4 - - FilePattern - - 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. - - regexp(s) - NO - NO - 1 - TryExec @@ -516,7 +520,7 @@ MimeType - The MIME type(s) supported by this entry. + The MIME type(s) supported by this application. string(s) NO @@ -540,8 +544,12 @@ StartupNotify If true, it is KNOWN that the application will send a "remove" - message when started with the DESKTOP_LAUNCH_ID environment variable - set (see the Startup Notification Protocol Specification for more details). + message when started with the DESKTOP_LAUNCH_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 Startup Notification Protocol Specification for more details). boolean NO @@ -551,7 +559,7 @@ StartupWMClass - If true, it is KNOWN that the application will map at least one + 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 Startup Notification Protocol Specification for more details). string @@ -620,48 +628,95 @@ NO 3 - - SortOrder - - This may specify the order in which to display files. - - string(s) - NO - NO - 4 - - List of valid <varname>Exec</varname> parameter variables + The <varname>Exec</varname> key - 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. + 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. - 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. + 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. + + + 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 ("'"), greater-than sign (">"), less-than sign + ("<"), tilde ("~"), vertical bar ("|"), ampersand ("&"), + semicolon (";"), dollar sign ("$"), asterisk ("*"), question mark ("?"), + equal sign ("="), hash mark ("#"), parenthesis ("(") and (")") and + backtick character ("`"). - - The escaping of the exec parameters is done in the way the mailcap - specification describes. Take a look at - RFC 1524 - for more information. - - Recognized fields are as follows: + 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 ("\\$"). + + + 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 %%. + 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. + + + 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. + + + 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 Exec 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. + + + Recognized field codes are as follows: + + + Code + Description + + %f @@ -682,6 +737,8 @@ 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. @@ -694,6 +751,8 @@ %U A list of URLs. + Each URL is passed as a separate argument to + the executable program. @@ -707,6 +766,8 @@ List of directories containing the files that would be passed in to a %F field. + Each directory is passed as a separate argument to + the executable program. @@ -719,23 +780,27 @@ %N A list of filenames (without paths). + Each filename is passed as a separate argument to + the executable program. %i - The Icon field of the desktop entry - expanded as two parameters, first - --icon and then the contents of the - Icon field. Should not expand as any - parameters if the Icon field is empty + The Icon key of the desktop entry + expanded as two arguments, first + --icon and then the value of the + Icon key. Should not expand to any + arguments if the Icon key is empty or missing. %c - The translated Name field associated with the desktop entry. + The translated name of the application as listed in + the appropriate Name key in the + desktop entry. @@ -749,7 +814,14 @@ %v - The name of the Device entry in the desktop file. + The device as listed in the Dev key in + the desktop file. + + + + %m + + Deprecated. @@ -760,18 +832,17 @@ Registering MIME Types The MimeType 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 + 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 Exec keyword. + using the command listed in the Exec key. 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 .desktop files. + Extending the format @@ -864,7 +936,7 @@ Comment=The best viewer for Foo objects available! TryExec=fooview Exec=fooview %F Icon=fooview.png -MimeType=image/x-foo +MimeType=image/x-foo; X-KDE-Library=libfooview X-KDE-FactoryName=fooviewfactory X-KDE-ServiceType=FooService @@ -944,12 +1016,12 @@ Icon=fooview-edit.png - Deprecated Exec parameters: + Deprecated Exec field codes: %m (the mini-icon associated with the - desktop entry, this should be expanded as two parameters, + desktop entry, this should be expanded as two arguments, --miniicon and the content of the - MiniIcon field, it can also be ignored by - expanding it to no parameters). + MiniIcon key, it can also be ignored by + expanding it to no arguments). @@ -975,6 +1047,25 @@ Icon=fooview-edit.png program to exec if swallowed app is clicked. + + + The SortOrder key is deprecated. It is of type + string(s) and may be used to specify the order in + which to display files. The Desktop + Menu Specification defines another mechanism for defining the + order of menu items. + + + + + The FilePattern key is deprecated. It is of type + regexp(s). 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. + + Historically some booleans have been represented by the numeric @@ -1010,7 +1101,7 @@ Icon=fooview-edit.png appropriate error indication to the user. - In the absence of an Encoding line, the implementation may choose + In the absence of an Encoding key, the implementation may choose to autodetect the encoding of the file by using such factors as: @@ -1029,7 +1120,7 @@ Icon=fooview-edit.png 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. + unsupported Encoding key. If the locale tag includes an .ENCODING part, then that determines -- cgit v1.2.3-70-g09d2