From b818b36ff0ee3c7f35df7b38db15a18b434f6375 Mon Sep 17 00:00:00 2001 From: lanius Date: Sat, 19 Jul 2003 13:13:46 +0000 Subject: version 0.9.4 --- desktop-entry/desktop-entry-spec.xml | 642 +++++++++++++++++++---------------- 1 file changed, 340 insertions(+), 302 deletions(-) (limited to 'desktop-entry/desktop-entry-spec.xml') diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml index d39e891..4bbbcb3 100644 --- a/desktop-entry/desktop-entry-spec.xml +++ b/desktop-entry/desktop-entry-spec.xml @@ -4,8 +4,8 @@
Desktop Entry Standard - Version 0.9.3 - 13 March 2001 + Version 0.9.4 + 7 July 2003 Preston @@ -52,9 +52,8 @@ Basic format of the file - 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 + These desktop entry files should have the extension ".desktop". + 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 @@ -63,8 +62,7 @@ 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]". + "group" header named "[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 @@ -79,7 +77,7 @@ those delimit the header. - Lines beginning with a "#" are considered comments and will be + Lines beginning with a "#" and blank lines are considered comments and will be ignored, however they should be preserved across reads / writes of the desktop entry file. @@ -108,14 +106,13 @@ Name=Value Possible value types - The value types recognized are string, localestring, regular expression, + The value types recognized are string, localestring, regexp, boolean (encoded as the string true/false), and numeric. 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.) + a string key must contain only ASCII characters and while the value + of a localestring key may contain UTF-8 characters. (See section 5.) Some keys can have multiple values; these should be separated by a @@ -128,42 +125,105 @@ Name=Value Recognized desktop entry keys - Keys may be postfixed by [locale], where locale is the LOCALE type - of the entry. locale 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. + Keys with type localestring may be postfixed by [LOCALE], + where LOCALE is the locale type of the + entry. LOCALE must be of the form + lang[_COUNTRY][ ENCODING][ MODIFIER], where _COUNTRY, .ENCODING, + and @MODIFIER may be omitted. If a postfixed key occurs, the same + key must be also present without the postfix. 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 locale 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 - .) + category against the locale postfixes + of all occurrences of the key, with the .ENCODING part stripped. + The .ENCODING field is used only when the Encoding key for the + desktop entry file is Legacy-Mixed, (see .) - The matching is done as follows: if the current value of - LC_MESSAGES is - lang_country.encoding@modifier, - then, if a key for - lang_country - is present, it will be used. Otherwise, if a key for - lang 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. + The matching of is done as follows. If LC_MESSAGES is of the form + LANG_COUNTRY.ENCODING@MODIFIER, + then it will match a key of the form + LANG_COUNTRY@MODIFIER. + If such a key does not exist, it will attempt to match + LANG_COUNTRY + followed by + LANG@MODIFIER. + Then, a match against LANG by itself + will be attempted. Finally, if no matching key is found the + required key without a locale specified is used. The encoding + from the LC_MESSAGES value is ignored when matching. + + If LC_MESSAGES does not have a MODIFIER + field, then no key with a modifier will be matched. Similarly, if + LC_MESSAGES does not have a COUNTRY + field, then no key with a country specified will be matched. If + LC_MESSAGES just has a LANG field, then + it will do a straight match to a key with a similar value. The + following table lists possible matches of various LC_MESSAGES in + the order in which they are matched. Note that the + ENCODING field isn't shown. + + + Locale Matching + + + + LC_MESSAGES Value + Possible Keys in Order of Matching + + + + + LANG_COUNTRY@MODIFIER + + LANG_COUNTRY@MODIFIER, + LANG_COUNTRY, + LANG@MODIFIER, + LANG, + Default Value + + + + LANG_COUNTRY + + LANG_COUNTRY, + LANG, + Default Value + + + + LANG@MODIFIER + + LANG@MODIFIER, + LANG, + Default Value + + + + LANG + + LANG, + Default Value + + + + +
+ For example, if the current value of the LC_MESSAGES category - is de_DE, and the desktop file includes: + is sr_YU Latn and the desktop file includes: Name=Foo - Name[de]=Foo auf Deutsch + Name[sr_YU]=... + Name[sr Latn]= + Name[sr]=... - 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. + then the value of the Name keyed by "sr_YU" is used. Case is significant. The keys "Name" and "NAME" are not equivalent. @@ -194,13 +254,14 @@ Name=Value Value Type REQ? MUST? + Type - Encoding + Type - encoding of the desktop entry file + There are 4 types of desktop entries: Application(1), Link(2), FSDevice(3) and Directory(4). string YES @@ -209,385 +270,311 @@ Name=Value Version - version of Desktop Entry Specification + Version of Desktop Entry Specification + (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). - numeric (4) + numeric NO YES + 1-4 - Name + Encoding - specific name of the application, for example "Mozilla" + Encoding of the whole desktop entry file (UTF-8 or LegacyMixed). - localestring + string YES YES + 1-4 - GenericName + Name - generic name of the application, for example "Web Browser" + Specific name of the application, for example "Mozilla". localestring YES YES + 1-4 - Type - - the type of desktop entry - - string (1) - YES - YES - - - 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 - - - TryExec + GenericName - filename of a binary on disk used to determine if the - program is actually installed. If not, entry may not - show in menus, etc. + Generic name of the application, for example "Web Browser". - string - NO + localestring NO + YES + 1-4 NoDisplay - whether not to display in menus, etc. + NoDisplay means "this application exists, but don't display it in the menus". + This can be useful to e.g. associate this application with mimetypes, so that + it gets launched from a file manager (or other apps), without having a menu + entry for it (there are tons of good reasons for this, including e.g. the + netscape -remote, or kfmclient openURL kind of stuff). boolean NO NO + 1-4 Comment - tooltip for the entry, for example "View sites on the - Internet"; should not be redundant with Name or - GenericName. + Tooltip for the entry, for example "View sites on the + Internet"; should not be redundant with Name or + GenericName. localestring NO YES + 1-4 - Exec + Icon - program to execute, possibly with arguments + 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. string NO YES + 1-4 - Actions + Hidden - additional actions possible, see MIME type discussion - in + Hidden should have been called Deleted. It means the user deleted (at his level) + something that was present (at an upper level, e.g. in the system dirs). It's + strictly equivalent to the .desktop file not existing at all, as far as that user is + concerned. This can also be used to "uninstall" existing files (e.g. due to a renaming) + - by letting "make install" install a file with Hidden=true in it. - string(s) + boolean NO - YES + NO + 1-4 - Icon + FilePattern - 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. + 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. - string + regexp(s) NO - YES + NO + 1 - MiniIcon + TryExec - small icon for menus, etc (deprecated). + Filename of a binary on disk used to determine if the + program is actually installed. If not, entry may not + show in menus, etc. string NO NO + 1 - Hidden + Exec - if true, pretend this entry doesn't exist. + Program to execute, possibly with arguments. - boolean - NO + string NO + YES + 1 Path - if entry is type Application, the working directory to run the program in. + If entry is type Application, the working directory to run the program in. string NO YES + 1 Terminal - whether the program runs in a terminal window + Whether the program runs in a terminal window - boolean (2) + boolean NO YES - - - TerminalOptions - - 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. - - string - NO - NO + 1 SwallowTitle - if entry is swallowed onto the panel, this should be the title of window + If entry is swallowed onto the panel, this should be the title of window localestring NO NO + 1 SwallowExec - program to exec if swallowed app is clicked + Program to exec if swallowed app is clicked. string NO NO + 1 - MimeType + Actions - the MIME type(s) supported by this entry + Additional actions possible, see MIME type discussion in . - regexp(s) - NO + string(s) NO + YES + 1 - Patterns + MimeType - if entry is type MimeType, various file name extensions - associated with the MIME type. + The MIME type(s) supported by this entry. regexp(s) NO NO + 1 - DefaultApp + SortOrder - if entry is type MimeType, the default application associated with this mime type + This may specify the order in which to display files. - string + string(s) NO NO + 4 Dev - if FSDevice type of entry, the device to mount + The device to mount. string NO NO + 3 FSType - The type of filesystem to try to mount + The type of filesystem to try to mount. string NO NO + 3 MountPoint - if FSDevice type of entry, the mount point of the device in question + The mount point of the device in question. string NO NO + 3 ReadOnly - if FSDevice type of entry, specifies whether or not the device is read-only + Specifies whether or not the device is read-only. - boolean (2) + boolean NO NO + 3 UnmountIcon - icon to display when device is not mounted Mounted devices display icon from Icon key + Icon to display when device is not mounted Mounted devices display icon from Icon key. + UnmountIcons may be localized with the UnmountIcon[xx]= syntax. string NO NO - - - SortOrder - - if entry of type Directory, this may specify the order in which to display files - - strings (3) - NO - NO + 3 URL - if entry is Link type, the URL to access - - string - NO - YES - - - BinaryPattern - - Deprecated. + If entry is Link type, the URL to access. string NO - NO - - - DocPath - - Deprecated. - - string - NO - NO - - - Extensions - - Deprecated. - - string - NO - NO - - - InitialPreference - - Deprecated. - - string - NO - NO + YES + 2 - Keywords + Categories - Deprecated. + Categories in which the entry should be shown in a menu (for possible values see the xdg-menu specification). - string + string(s) NO NO + 1 - MapNotify + OnlyShowIn / NotShowIn - Deprecated. + A list of strings identifying the environments that should display/not display a given .desktop item. Only one of these keys, either OnlyShowIn or NotShowIn, may appear in a Group. (for possible values see the xdg-menu specification) - string + string(s) NO NO + 1-4 - Protocols + StartupNotify - Deprecated. + 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 spec for more details). - string + boolean NO NO + 1 - ServiceTypes + StartupWMClass - Deprecated. + If true, 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 spec for more details). string NO NO + 1 - - Notes: - - - - - possible values are Application, Link, FSDevice, MimeType, Directory, - Service, ServiceType - - - - - 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. - - - - - 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. - - - - - 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. - - - Character set encoding of the file @@ -595,39 +582,35 @@ Name=Value Desktop entry files are encoded as lines of 8-bit characters separated by LF characters. - - Except for comments and values of type localestring, only ASCII - characters are permitted in the file: - - - Key names must contain only the characters 'A-Za-z0-9-' - + + Key names must contain only the characters 'A-Za-z0-9-' + - - Group names may contain all ASCII characters except for control - characters and '[' and ']'. - + + Group names may contain all ASCII characters except for control + characters and '[' and ']'. + - - Values of type string may contain all ASCII characters except - for control characters. - + + Values of type string may contain all ASCII characters except + for control characters. + - - Values of type boolean must either be the string 'true' or - 'false' - + + Values of type boolean must either be the string 'true' or + 'false'. + - - Numeric values must be a valid floating point number as recognized - by the %f specifier for scanf. - + + Numeric values must be a valid floating point number as recognized + by the %f specifier for scanf. + @@ -635,46 +618,10 @@ Name=Value (except for LF). However, using UTF-8 for comment lines that contain characters not in ASCII is encouraged. - - 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.) - - - 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'. - - - 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. - - - In the absence of an Encoding line, the implementation may choose - to autodetect the encoding of the file by using such factors - as: - - - - The location of the file on the filesystem - - - - - Whether the contents of the file are valid UTF-8 + The encoding for values of type localestring is determined by the + Encoding field. - - - - 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. - List of valid Exec parameter variables @@ -691,6 +638,12 @@ Name=Value 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. + Recognized fields are as follows: @@ -761,12 +714,6 @@ Name=Value the icon associated with the desktop entry - - %m - - the mini-icon associated with the desktop entry - - %c @@ -883,11 +830,11 @@ Exec=sp -edit %u [Desktop Entry] Version=1.0 Type=Application +Encoding=UTF-8 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 @@ -903,8 +850,74 @@ Exec=fooview --edit %f Name=Foo Viewer (edit image) Icon=fooview-edit.png + + Currently reserved for use within KDE + + During the time KDE added some extensions that are currently not prefixed by the "X-" prefix, but should be in future KDE releases. + + + + + Keys added by KDE: ServiceTypes, DocPath, Keywords, InitialPreference + + + + + Types added by KDE: ServiceType, Service + + + + + + Deprecated Items + + As this standard is quite old there are some deprecated items that may or may not be used by serveral implementations. + + + + + Type=MimeType is deprecated as there is a new standard for this now: http://www.freedesktop.org/standards/shared-mime-info.html for more information. In consequence the Keys 'Patterns' (various file name extensions associated with the MIME type.) and 'DefaultApp' (the default application associated with this mime type) are also deprecated. + + + + + Using .kdelnk instead of .desktop as file-extension is deprecated. + + + + + Using "[KDE Desktop Entry]" instead of "[Desktop Entry]" as header is deprecated. + + + + + Encoding=LegacyMixed, which allowed localestrings in the encoding of the specified locale, is deprecated. + + + + + Deprecated ExecParameters: %m (the mini-icon associated with the desktop entry) + + + + + Deprecated Keys: MiniIcon (small icon for menus, etc), TerminalOptions (if the program runs in a terminal, any options that should be passed to the terminal emulator before actually executing the program), Protocols, Extensions, BinaryPattern, MapNotify. + + + + + Historically some booleans 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. + + + + + Historically lists have been comma separated . 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. + + + + - The Legacy-Mixed encoding + The Legacy-Mixed encoding (Deprecated) The Legacy-Mixed encoding corresponds to the traditional encoding of desktop files in older versions of the GNOME and KDE desktop @@ -913,13 +926,39 @@ Icon=fooview-edit.png without a locale tag, the value must contain only ASCII characters. + + 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. + + + In the absence of an Encoding line, the implementation may choose + to autodetect the encoding of the file by using such factors + as: + + + + + The location of the file on the filesystem + + + + + Whether the contents of the file are valid UTF-8 + + + + + 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. + 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.) + to the following table. @@ -932,7 +971,7 @@ Icon=fooview-edit.png - ARMSCII-8 (*)hy + ARMSCII-8 (*)by BIG5zh_TW @@ -948,7 +987,7 @@ Icon=fooview-edit.png GEORGIAN-PS (*)ka - ISO-8859-1br ca da de en es eu fi fr gl it nl wa no pt sv + ISO-8859-1br ca da de en es eu fi fr gl it nl no pt sv wa ISO-8859-2cs hr hu pl ro sk sl sq sr @@ -962,7 +1001,7 @@ Icon=fooview-edit.png ISO-8859-13lt lv mi - ISO-8859-14ga cy + ISO-8859-14cy ga ISO-8859-15et @@ -1031,4 +1070,3 @@ Icon=fooview-edit.png
- -- cgit v1.2.3-54-g00ecf