From 9c493d5fca5fcceca4e1bc0b2b2ba8a13c5eb12e Mon Sep 17 00:00:00 2001 From: otaylor Date: Thu, 8 Mar 2001 17:38:23 +0000 Subject: Initial revision --- desktop-entry/desktop-entry-spec.sgml | 880 ++++++++++++++++++++++++++++++++++ 1 file changed, 880 insertions(+) create mode 100644 desktop-entry/desktop-entry-spec.sgml (limited to 'desktop-entry/desktop-entry-spec.sgml') diff --git a/desktop-entry/desktop-entry-spec.sgml b/desktop-entry/desktop-entry-spec.sgml new file mode 100644 index 0000000..25bab48 --- /dev/null +++ b/desktop-entry/desktop-entry-spec.sgml @@ -0,0 +1,880 @@ + +
+ + Desktop Entry Standard + Version 0.9.2 + 6 March 2001 + + + Preston + Brown + +
+ pbrown@kde.org +
+ + + + Jonathan + Blandford + +
+ jrb@redhat.com +
+ + + + Owen + Taylor + +
+ otaylor@gtk.org +
+ + + + + + + Introduction + + Both the KDE and GNOME desktop environments have adopted a similar + format for "desktop entries," or configuration files describing how a + particular program is to be launched, how it appears in menus, etc. + It is to the larger community's benefit that a unified standard be + agreed upon by all parties such that interoperation between the two + environments, and indeed any additional environments that implement + the specification, becomes simpler. + + + + 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 + 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 + a directory is to be formatted/displayed should be simply called + ".directory". + + + 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]". + 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 + 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). + + + Lines beginning with a "#" are considered comments and will be + ignored, however they should be preserved across reads / writes of the + desktop entry file. + + + Compliant implementations MUST not remove any fields from the file, + even if they don't support them. Such fields must be maintained in a + list somewhere, and if the file is "rewritten," they will be included. + This ensures that any desktop-specific extensions will be preserved + even if another system accesses and changes the file. + + + Entries in the file are {key,value} pairs in the format: + + +Name=Value + + Space before and after the equals sign should be supported; the "=" + sign is the actual delimiter. + + + + Possible value types + + The value types recognized are string, localestring, regular expression, + 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 ASCII characters and while the value + of a localestring key may contain localized encodings. (See + section 5.) + + + 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. + + + + 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. + + + 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 + .) + + + 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. + + + For example, if the current value of the LC_MESSAGES category + is de_DE, and the desktop file includes: + + + Name=Foo + Name[de]=Foo auf Deutsch + + 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. + + + Case is significant. The keys "Name" and "NAME" are not equivalent. + The same holds for group names. Key values are case sensitive as + well. + + + Keys are either OPTIONAL or REQUIRED. If a key is optional it may or + may not be present in the file. However, if it isn't, the + implementation of the standard should not blow up, it must provide + some sane defaults. Additionally, keys either MUST or MAY be + supported by a particular implementation. + + + Some keys only make sense in the context when another particular key + is also present. + + + Some example keys: Name[C], Comment[it]. + + + Standard Keys + + + + Key + Description + Value Type + REQ? + MUST? + + + + + Encoding + + encoding of the desktop entry file + + string + YES + YES + + + Version + + version of Desktop Entry Specification + + numeric (4) + NO + YES + + + Name + + name of the entry, need not match binary name + + localestring + YES + YES + + + 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 + + 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 + + + NoDisplay + + whether not to display in menus, etc. + + boolean + NO + NO + + + Comment + + descriptive comment + + localestring + NO + YES + + + Exec + + program to execute, possibly with arguments + + string + NO + YES + + + Actions + + additional actions possible, see MIME type discussion + in + + string(s) + NO + YES + + + Icon + + icon to display in file manager, menus, etc. the icon + MAY specify a specific path to override common search + directories + + string + NO + YES + + + MiniIcon + + small icon for menus, etc (deprecated). + + string + NO + NO + + + Hidden + + if true, pretend this entry doesn't exist. + + boolean + NO + NO + + + Path + + if entry is type Application, the working directory to run the program in. + + string + NO + YES + + + Terminal + + whether the program runs in a terminal window + + boolean (2) + 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 + + string + NO + NO + + + SwallowTitle + + if entry is swallowed onto the panel, this should be the title of window + + localestring + NO + NO + + + SwallowExec + + program to exec if swallowed app is clicked + + string + NO + NO + + + MimeType + + the MIME type(s) supported by this entry + + regexp(s) + NO + NO + + + Patterns + + if entry is type MimeType, various file name extensions + associated with the MIME type. + + regexp(s) + NO + NO + + + DefaultApp + + if entry is type MimeType, the default application associated with this mime type + + string + NO + NO + + + Dev + + if FSDevice type of entry, the device to mount + + string + NO + NO + + + FSType + + The type of filesystem to try to mount + + string + NO + NO + + + MountPoint + + if FSDevice type of entry, the mount point of the device in question + + string + NO + NO + + + ReadOnly + + if FSDevice type of entry, specifies whether or not the device is read-only + + boolean (2) + NO + NO + + + UnmountIcon + + icon to display when device is not mounted Mounted devices display icon from Icon key + + string + NO + NO + + + SortOrder + + if entry of type Directory, this may specify the order in which to display files + + strings (3) + NO + NO + + + URL + + if entry is Link type, the URL to access + + string + NO + YES + + + +
+ + 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 + + 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-' + + + + + 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 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. + + + + + Comment lines are uninterpreted and may contain any character + (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 + + + + + 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 + + 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. Recognized fields are as follows: + + + + + + %f + + a single file name, even if multiple files are selected. The system + reading the Desktop Entry should recognize that the program in + question cannot handle multiple file arguments, and it should + should probably spawn and execute multiple copies of a program + for each selected file if the program is not able to handle + additional file arguments. If files are not on the local file system + (i.e. HTTP or FTP locations), the files will be copied to the local + file system and %f will be expanded to point at the temporary + file. Used for programs that do not understand URL syntax. + + + + %F + + a list of files. Use for apps that can open several local + files at once. + + + + %u + + a single URL. + + + + %U + + a list of URLs. + + + + %d + + the directory of the file to open. + + + + %D + + a list of directories + + + + %n + + a single filename (without path) + + + + %N + + a list of filenames (without path) + + + + %i + + the icon associated with the desktop entry + + + + %m + + the mini-icon associated with the desktop entry + + + + %c + + the comment associated with the desktop entry + + + + %k + + the name of the desktop file + + + + %v + + the name of the Device entry in the desktop file + + + + + + + + Detailed discussion of supporting MIME types + + It is in every desktop's best interest to have thorough support for + mime types. The old /etc/mailcap and /etc/mime.types 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 Standard + hopes to be able to provide the beginnings of a solution to this + problem. + + + At a very basic level, the "Exec" 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 "kedit %f" or "ee %f". This is a good + start, but it isn't as flexible as it can be. + + + 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 toplevel "Exec" 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. + + + Let us use a sound player as a simple example. Call it sp. The + default Exec (Open) action for this program would likely look + something like: + + +Exec=sp %u + + 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 accomodate this. Adding the action would be performed + like this: + + +Actions=Edit; + +[Desktop Action Edit] +Exec=sp -edit %u + + As you can see, defining the action "edit" will enable an additional + group of the name [Desktop Action actionname] to be read. This + group can contain an additional Exec line, as well as possibly other + information like a new Name, Comment, Icon, and Path. 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. + + + If no DefaultApp 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 DefaultApp anymore, but assigns + a Preference number to each program, so that the highest number is the + one chosen for handling the MIME type. + + + + Extending the format + + If the standard is to be amended with a new {key,value} pair which + should be applicable to all supporting parties, a group discussion + will take place. This is the preferred method for introducing + changes. If one particular party wishes to add a field for personal + use, they should prefix the key with the string "X-PRODUCT", + i.e. "X-NewDesktop-Foo", following the precedent set by other IETF and RFC + standards. + + + Alternatively, fields can be placed in their own group, where they may + then have arbitrary key names. If this is the case, the group should + follow the scheme outlined above, i.e. [X-PRODUCT GROUPNAME] or + something similar. These steps will avoid namespace clashes between + different yet similar environments. + + + + Example Desktop Entry File + +[Desktop Entry] +Version=1.0 +Type=Application +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 +X-KDE-FactoryName=fooviewfactory +X-KDE-ServiceType=FooService + +[Desktop Action Inverse] +Exec=fooview --inverse %f +Name=Foo Viewer (inverse image) + +[Desktop Action Edit] +Exec=fooview --edit %f +Name=Foo Viewer (edit image) +Icon=fooview-edit.png + + + The Legacy-Mixed encoding + + The Legacy-Mixed encoding corresponds to the traditional encoding + of desktop files in older versions of the GNOME and KDE desktop + files. In this encoding, the encoding of each localestring key + is determined by the locale tag for that key, if any. For keys + without a locale tag, the value must contain only ASCII + characters. + + + 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, according + to the following table. + + + + + + Encoding + Tags + + + + + ARMSCII-8 (*)by + + BIG5zh_TW.Big5 + + CP1251be bg + + EUC-CNzh_CN.GB2312 + + EUC-JPja + + EUC-KRko + + GEORGIAN-ACADEMY (*)ka_GE.georgianacademy + + GEORGIAN-PS (*)ka + + ISO-8859-1br ca da de en es eu fi fr gl it nl wa no pt pt sv + + ISO-8859-2cs hr hu pl ro sk sl sq sr + + ISO-8859-3 eo + + ISO-8859-5mk sp + + ISO-8859-7el + + ISO-8859-9tr + + ISO-8859-13lt lv mi + + ISO-8859-14ga cy + + ISO-8859-15et + + KOI8-Rru + + KOI8-Uuk + + TCVN-5712 (*)vi vi_VN.TCVN + + TIS-620th + + + + + + Encodings marked with a (*) are not currently supported by the GNU C + Library; for this reason, implementations may choose to ignore lines + in desktop files with the corresponding tags. Desktop files with + these tags are currently rare or non-existent. + + + The encoding here is listed according to its canonical name in the + GNU C Library's iconv facility. The more common tags tags found + with an encoding part are listed here, so that implementors can + verify that the correct encoding will be used. (In particular, + note the mismatch between zh_CN.GB2312, and the canonical name + EUC-CN.) + + +
+ -- cgit v1.2.3-70-g09d2