Desktop Entry Specification
+ 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.
+
+ 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 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]. 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, 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).
+
+ Group headers may not contain the characters [ and
+ ] as those delimit the header.
+
+ Lines beginning with a # and blank lines are
+ considered comments and will be ignored, however they should be
+ preserved across reads and 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:
+
Key=Value
+ Space before and after the equals sign should be ignored; the =
+ sign is the actual delimiter.
+
+ The escape sequences \s, \n,
+ \t, \r, and
+ \\ are supported, meaning ASCII space, newline,
+ tab, carriage return, and backslash, respectively.
+
+ The value types recognized are string, localestring, regexp,
+ boolean (encoded as the string true/false), and numeric.
+
+ Values of type string must contain only ASCII
+ characters excluding control characters. Values of type
+ localestring are user displayable, and are
+ encoded in UTF-8 unless the Legacy-Mixed
+ Encoding is specified (see Appendix D, The Legacy-Mixed Encoding (Deprecated).)
+
+ 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. Semicolons in these values
+ need to be escaped using \;.
+
Recognized desktop entry keys
+ 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 field is
+ used only when the value of the Encoding key
+ for the desktop entry file is Legacy-Mixed
+ (see Appendix D, The Legacy-Mixed Encoding (Deprecated).)
+
+ 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 values in
+ the order in which they are matched. Note that the
+ ENCODING field isn't shown.
+
Table 1. 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 sr_YU@Latn and the desktop file includes:
+
+ Name=Foo
+ Name[sr_YU]=...
+ Name[sr@Latn]=...
+ Name[sr]=...
+ then the value of the Name keyed by sr_YU is used.
+
+ 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].
+
Table 2. Standard Keys
| Key | Description | Value Type | REQ? | MUST? | Type |
|---|
| Type |
+ There are 4 types of desktop entries:
+ Application,
+ Link, FSDevice
+ and Directory.
+ | string | YES | YES |
| Version |
+ 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 | NO | YES | 1-4 |
| Encoding |
+ Encoding of the whole desktop entry file
+ (UTF-8 or
+ Legacy-Mixed).
+ | string | YES | YES | 1-4 |
| Name |
+ Specific name of the application, for example "Mozilla".
+ | localestring | YES | YES | 1-4 |
| GenericName |
+ Generic name of the application, for example "Web Browser".
+ | localestring | NO | YES | 1-4 |
| NoDisplay | NoDisplay means "this application exists, but don't display it in the menus".
+ This can be useful to e.g. associate this application with MIME types, 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.
+ | localestring | NO | YES | 1-4 |
| Icon |
+ 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 |
| Hidden | 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.
+ | boolean | NO | 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 |
+ File name 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 |
| Exec |
+ Program to execute, possibly with arguments.
+ | string | NO | YES | 1 |
| Path |
+ If entry is of type Application, the working directory to run the program in.
+ | string | NO | YES | 1 |
| Terminal |
+ Whether the program runs in a terminal window.
+ | boolean | NO | YES | 1 |
| SwallowTitle |
+ If entry is swallowed onto the panel, this should be the title of the window.
+ | localestring | NO | NO | 1 |
| SwallowExec |
+ Program to exec if swallowed app is clicked.
+ | string | NO | NO | 1 |
| Actions |
+ Additional actions possible, see MIME type discussion in the section called “Registering MIME Types”.
+ | string(s) | NO | YES | 1 |
| MimeType |
+ The MIME type(s) supported by this entry.
+ | strings(s) | NO | NO | 1 |
| SortOrder |
+ This may specify the order in which to display files.
+ | string(s) | NO | NO | 4 |
| Dev |
+ The device to mount.
+ | string | NO | NO | 3 |
| FSType |
+ The type of file system to try to mount.
+ | string | NO | NO | 3 |
| MountPoint |
+ The mount point of the device in question.
+ | string | NO | NO | 3 |
| ReadOnly |
+ Specifies whether or not the device is read only.
+ | boolean | NO | NO | 3 |
| UnmountIcon |
+ Icon to display when device is not mounted. Mounted devices display icon from the Icon key.
+ UnmountIcons may be localized with the UnmountIcon[xx]= syntax.
+ | string | NO | NO | 3 |
| URL |
+ If entry is Link type, the URL to access.
+ | string | NO | YES | 2 |
| Categories |
+ Categories in which the entry should be shown in a menu (for
+ possible values see the Desktop
+ Menu Specification).
+ | string(s) | NO | NO | 1 |
| OnlyShowIn, NotShowIn |
+ A list of strings identifying the environments that should
+ display/not display a given desktop entry. Only one of
+ these keys, either OnlyShowIn or
+ NotShowIn, may appear in a group (for
+ possible values see the Desktop
+ Menu Specification).
+ | string(s) | NO | NO | 1-4 |
| 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).
+ | boolean | NO | NO | 1 |
| StartupWMClass |
+ 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 Protocol Specification for more details).
+ | string | NO | NO | 1 |
Character set encoding of the file
+ Desktop entry files are encoded as lines of 8-bit characters separated
+ by LF characters.
+
+ Key names must contain only the characters A-Za-z0-9-
+
+ Group names may contain all ASCII characters except for
+ [ and ] and 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.
+
+ 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.
+
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.
+
+ Recognized fields are as follows:
+
+ 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
+ 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.
+
+ 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.
+
+ To make parsing of all the desktop files less costly, a
+ update-desktop-database program is provided
+ that will generate a cache file. The concept is identical to
+ that of the 'update-mime-database' program in that it lets
+ applications avoid reading in (potentially) hundreds of files.
+ It will need to be run after every desktop file is installed.
+ One cache file is created for every directory in
+ $XDG_DATA_DIRS/applications/, and will create a file called
+ $XDG_DATA_DIRS/applications/mimeinfo.cache.
+
+ The format of the cache is similar to that of the desktop file,
+ and is just a list mapping mime-types to desktop files. Here's
+ a quick example of what it would look like:
+
application/x-foo=foo.desktop;bar.desktop;
+application/x-bar=bar.desktop;
+ Each MIME Type is listed only once per cache file, and the
+ desktop-id is expected to exist in that particular directory.
+ That is to say, if the cache file is located at
+ /usr/share/applications/mimeinfo.cache,
+ bar.desktop refers to the file
+ /usr/share/applications/bar.desktop.
+
Priority of MIME Types and desktop files
+ There is also a preference list to determine preferred
+ application of a given MIME Type. It defines the 'default'
+ application to handle a given MIME Type. It has the same format
+ as the cache list.
+
mime/type=desktop-id.desktop;
+ If a mime type is listed multiple times (either in the same
+ 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 OnlyShowIn or
+ NotShowIn files, 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
+ one can be tested, etc.
+
+ It is also worth noting who this mechanism is defined for. It
+ is primarily intended for use by distributors/sysadmins to
+ provide a sane set of defaults for their users. Additionally,
+ users themselves can use this mechanism to override the user
+ defaults. We intentionally don't provide a way for application
+ authors themselves to list themselves as the default for a given
+ type, as we felt that that cannot work.
+
+ 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,
+ e.g. 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.
+
A. Example Desktop Entry File
+[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
+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
B. 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
+
+ As this standard is quite old there are some deprecated items that
+ may or may not be used by several implementations.
+
+ Type=MimeType is deprecated as there is a
+ new standard for this now, see the Shared
+ MIME-info Database specification 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 the file extension is
+ deprecated.
+
+ Using [KDE Desktop Entry] instead of
+ [Desktop Entry] as header is deprecated.
+
+ Encoding=Legacy-Mixed, which allowed
+ localestrings in the encoding of the specified locale, is
+ deprecated.
+
+ Deprecated Exec parameters:
+ %m (the mini-icon associated with the
+ desktop entry, this should be expanded as two parameters,
+ --miniicon and the content of the
+ MiniIcon field, it can also be ignored by
+ expanding it to no parameters).
+
+ 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.
+
D. 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
+ 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 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:
+
+ 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
+ lang_COUNTRY
+ pair from the locale tag, according to the following table.
+
- Encoding
+ The name given here is listed here is typically the
+ canonical name for the encoding in the GNU C Library's
+ iconv facility. Encodings marked with (*) are not
+ currently supported by the GNU C Library; for this reason,
+ implementations may choose to ignore lines in desktop
+ files that resolve to this encoding. Desktop files with
+ these encodings are currently rare or non-existent.
+
- Aliases
+ Other names for the encoding found in existing desktop
+ files.
+
- Tags
+ Language tags for which this is the default encoding.
+
+ This table above covers all tags and encodings that are known to
+ be currently in use. Implementors may choose to support
+ encodings not in the above set. For tags without defaults listed
+ in the above table, desktop file creators must specify the
+ .ENCODING part of the locale tag.
+
+ Matching the .ENCODING part of the locale tag against a locale
+ name or alias should be done by stripping all punctuation
+ characters from both the tag and the name or alias, converting
+ both name and alias to lowercase, and comparing the result.
+ This is necessary because, for example, Big5 is frequently
+ found instead of BIG5 and georgianacademy instead of
+ GEORGIAN-ACADEMY. Desktop files creators should, however, use
+ the name as it appears in the "Encoding" column above.
+
Desktop Menu Specification
+ This DRAFT document defines how to construct a user-visible hierarchy of
+ applications, typically displayed as a menu. It allows third-party
+ software to add menu items that work for all desktops, and allows system
+ administrators to edit menus in a way that affects all desktops.
+
+ The basic scheme is very simple. Information about each application (menu
+ item) is stored in a desktop entry (see Desktop
+ Entry Standard). Then an XML configuration file defines the
+ hierarchical arrangement (layout) of menu items, and which menu items are
+ actually displayed.
+
+ Things are complicated somewhat by the need to support legacy desktop
+ entry hierarchies, and the need to allow third parties to extend the menu
+ layout. Both of these issues are addressed by the idea of
+ merging two menu layouts.
+
+ In addition to a strict definition of the contents of each menu this
+ specification also forsees in a number of layout / presentation hints.
+ This part of the specification is optional, implementations may chose to
+ ignore these hints.
+
+ Files involved in this specification are located according to the "desktop
+ base directory specification" which can be found on www.freedesktop.org.
+
+ Here are the files defined by this specification:
+
- $XDG_CONFIG_DIRS/menus/applications.menu
+ This file contains the XML definition of the main application menu
+ layout. The first file found in the search path should be used;
+ other files are ignored. This implies that if the user has
+ their own applications.menu, it replaces the systemwide one.
+ (Though the user's menu may explicitly merge the systemwide one.)
+
+ Other menu files may exist, but are not specified in this
+ document.
+
- $XDG_CONFIG_DIRS/menus/menu-file-basename-merged/
+ The default merge directories included in the
+ <DefaultMergeDirs> element. By convention, third parties
+ may add new <Menu> files in this
+ location. menu-file-basename means the
+ "applications" from "applications.menu" for example. So the merge
+ directory would be "applications-merged".
+
- $XDG_DATA_DIRS/applications/
+ This directory contains a .desktop file for each possible menu
+ item. Each directory in the $XDG_DATA_DIRS
+ search path should be used (i.e. desktop entries are collected
+ from all of them, not just the first one that exists). When two
+ desktop entries have the same name, the one appearing earlier in
+ the path is used.
+
+ The <DefaultAppDirs> element in a menu file indicates that
+ this default list of desktop entry locations should be scanned at
+ that point. If a menu file does not contain
+ <DefaultAppDirs>, then these locations are not scanned.
+
- $XDG_DATA_DIRS/desktop-directories/
+ This directory contains directory entries which may be associated
+ with folders in the menu layout. Each directory
+ in the search path should be used. Only files ending in
+ .directory are used; other files are ignored.
+
+ The <DefaultDirectoryDirs> element in a menu file indicates that
+ this default list of directory entry locations should be scanned at
+ that point. If a menu file does not contain
+ <DefaultDirectoryDirs>, then these locations are not scanned.
+
+
Extensions to the desktop entry format
+ This specification adds two new fields to desktop
+entries: Categories,
+ OnlyShowIn and NotShowIn.
+
+ The Categories field is a list of strings used to
+ classify menu items. For example, applications in the
+ AudioVideo category might end up in the "Sound &
+ Video" submenu. Appendix A, Registered Categories enumerates the
+ standard categories. Categories not in this document must be prefixed
+ by the string "X-" indicating that they are extensions. Categories
+ are case-sensitive.
+
+ Desktop entries should list all categories that clearly apply. They should
+ not list categories that only vaguely or possibly apply, because the user
+ will end up seeing the same desktop entry in a half-dozen places. But
+ it's typical that several categories will apply to a given desktop entry.
+
+ The OnlyShowIn field is a list of strings identifying
+ the environments that should display a given menu item. If an
+ OnlyShowIn field is present, a given environment should
+ only display the menu item if the string identifying that environment is
+ present. The strings are case-sensitive. Appendix B, Registered OnlyShowIn Environments enumerates the strings to use for
+ some common environments.
+
+ The NotShowIn field is a list of strings identifying
+ the environments that should not display a given menu item. If an
+ NotShowIn field is present, a given environment should
+ only display the menu item if the string identifying that environment is
+ not present. The strings are case-sensitive. Appendix B, Registered OnlyShowIn Environments enumerates the strings to use for
+ some common environments.
+
Examples of using Categories and OnlyShowIn
+ A desktop entry for a Qt-based image viewer might contain
+ this Categories line:
+
+
+ A desktop entry for Octave, a command-line mathematics program (which
+ would also have the field Terminal=true), might have:
+
+
+ A desktop entry for a GNOME-specific calculator program
+ that should only appear in GNOME might have:
+
+ Note that the OnlyShowIn field is a
+ list and thus ends in a semicolon.
+
+ Menu files must be well-formed XML files, conform to the menu file DTD,
+ and end in the extension ".menu". DTD conformance implies that
+ implementation-specific extensions to the file format are not allowed;
+ implementations are expected to stop processing if they encounter XML
+ elements or attributes that are not specified in this document.
+
+ Menu files for this version of the specification must use the following
+ namespace, public and system identifiers:
+
- Namespace
+ http://www.freedesktop.org/standards/menu
+
- Public Identifier for 0.8
+ PUBLIC "-//freedesktop//DTD Menu 0.8//EN"
+
- System Identifier for 0.8
+ http://www.freedesktop.org/standards/menu-spec/menu-0.8.dtd
+
+
+ Here is a sample doctype declaration:
+
+
+ All menu files MUST include the doctype declaration, so that
+ implementations can adapt to different versions of this specification
+ (and so implementations can validate the menu file against
+ the DTD).
+
+
- <Menu>
+ The root element is <Menu>. Each <Menu> element may
+ contain any number of nested <Menu> elements, indicating submenus.
+
- <AppDir>
+ This element may only appear below <Menu>. The
+ content of this element is a directory name. Desktop entries
+ in this directory are scanned and added to the pool of entries
+ which can be included in this <Menu> and its submenus.
+ Only files ending in ".desktop" should be used, other files are
+ ignored.
+
+ Desktop entries in the pool of available entries are identified
+ by their desktop-file id (see Desktop-File Id).
+ The desktop-file id of a desktop entry is equal to its filename,
+ with any path components removed.
+ So given a <AppDir>
+ /foo/bar and desktop entry
+ /foo/bar/Hello.desktop the desktop
+ entry would get a desktop-file id of Hello.desktop
+
+ If the directory contains sub-directories then these sub-directories
+ should be (recursively) scanned as well. The name of the subdirectory
+ should be added as prefix to the desktop-file id together with a dash character ("-")
+ So given a <AppDir>
+ /foo/bar and desktop entry
+ /foo/bar/booz/Hello.desktop the desktop
+ entry would get a desktop-file id of booz-Hello.desktop
+ A desktop entry /foo/bar/bo/oz/Hello.desktop would result
+ in a desktop-file id of bo-oz-Hello.desktop
+
+ <AppDir> elements appearing later in the menu file have
+ priority in case of collisions between desktop-file ids.
+
+ If the filename given as an <AppDir> is not an absolute
+ path, it should be located relative to the location of the menu
+ file being parsed.
+
+ Duplicate <AppDir> elements (that specify the same
+ directory) should be ignored, but the last
+ duplicate in the file should be used when establishing the order
+ in which to scan the directories. This is important when merging
+ (see the section called “Merging”). The order of
+ <AppDir> elements with respect to <Include> and
+ <Exclude> elements is not relevant, also to facilitate
+ merging.
+
- <DefaultAppDirs>
+ This element may only appear below <Menu>. The element has
+ no content. The element should be treated as if it were a list
+ of <AppDir> elements containing the default app dir
+ locations
+ (datadir/applications/ etc.). When expanding
+ <DefaultAppDirs> to a list of <AppDir>, the default
+ locations that are earlier in the search path go later in the
+ <Menu> so that they have priority.
+
- <DirectoryDir>
+ This element may only appear below <Menu>. The content of
+ this element is a directory name. Each directory listed in a
+ <DirectoryDir> element will be searched for directory
+ entries to be used when resolving the <Directory> element
+ for this menu and its submenus.
+ If the filename given as a <DirectoryDir> is not an absolute path,
+ it should be located relative to the location
+ of the menu file being parsed.
+
+ Directory entries in the pool of available entries are identified
+ by their relative path (see Relative path).
+
+ If two directory entries have duplicate relative paths, the one from
+ the last (furthest down) element in the menu file must be used.
+ Only files ending in the extension ".directory" should be
+ loaded, other files should be ignored.
+
+ Duplicate <DirectoryDir> elements (that specify the same
+ directory) are handled as with duplicate <AppDir>
+ elements (the last duplicate is used).
+
- <DefaultDirectoryDirs>
+ This element may only appear below <Menu>. The element has
+ no content. The element should be treated as if it were a list
+ of <DirectoryDir> elements containing the default desktop dir
+ locations
+ (datadir/desktop-directories/ etc.). The default
+ locations that are earlier in the search path go later in the
+ <Menu> so that they have priority.
+
- <Name>
+ Each <Menu> element must have a single <Name>
+ element. The content of the <Name> element is a name to
+ be used when referring to the given menu. Each submenu of a
+ given <Menu> must have a unique name. <Menu>
+ elements can thus be referenced by a menu path, for example
+ "Applications/Graphics." The <Name> field must not contain
+ the slash character ("/"); implementations should discard
+ any name containing a slash. See also Menu path.
+
- <Directory>
+ Each <Menu> element has any number of <Directory>
+ elements. The content of the <Directory> element
+ is the relative path of a directory entry containing metainformation
+ about the <Menu>, such as its icon and localized name.
+ If no <Directory> is specified for a <Menu>,
+ its <Name> field should be used as the user-visible
+ name of the menu.
+
+ Duplicate <Directory> elements are allowed in order
+ to simplify menu merging, and allow user menus to override
+ system menus. The last <Directory> element to appear
+ in the menu file "wins" and other elements are ignored,
+ unless the last element points to a nonexistent directory
+ entry, in which case the previous element should be tried instead,
+ and so on.
+
- <OnlyUnallocated> and <NotOnlyUnallocated>
+ Each <Menu> may contain any number of
+ <OnlyUnallocated> and <NotOnlyUnallocated>
+ elements. Only the last such element to appear is relevant, as
+ it determines whether the <Menu> can contain any desktop
+ entries, or only those desktop entries that do not match other
+ menus. If neither <OnlyUnallocated> nor
+ <NotOnlyUnallocated> elements are present, the default
+ is <NotOnlyUnallocated>.
+
+ To handle <OnlyUnallocated>, the menu file must be
+ analyzed in two conceptual passes. The first pass processes
+ <Menu> elements that can match any desktop entry. During
+ this pass, each desktop entry is marked according to whether it
+ was included in some <Menu>. The second pass processes
+ only <Menu> elements that are restricted to unallocated
+ desktop entries. During the second pass, queries may only match
+ desktop entries that were not allocated to some menu during the
+ first pass. See the section called “Generating the menus”.
+
- <Deleted> and <NotDeleted>
+ Each <Menu> may contain any number of <Deleted> and
+ <NotDeleted> elements. Only the last such element to
+ appear is relevant, as it determines whether the <Menu>
+ has been deleted. If neither <Deleted> nor
+ <NotDeleted> elements are present, the default is
+ <NotDeleted>. The purpose of this element is to support
+ menu editing. If a menu contains a <Deleted> element
+ not followed by a <NotDeleted> element, that menu
+ should be ignored.
+
- <Include>
+ An <Include> element is a set of rules attempting to match
+ some of the known desktop entries. The <Include> element
+ contains a list of any number of matching rules. Matching rules
+ are specified using the elements <And>, <Or>,
+ <Not>, <All>, <Filename>, and
+ <Category>. Each rule in a list of rules has a logical OR
+ relationship, that is, desktop entries which match any rule
+ are included in the menu.
+
+ <Include> elements must appear immediately under
+ <Menu> elements. The desktop entries they match are
+ included in the menu. <Include> and <Exclude>
+ elements for a given <Menu> are processed in order,
+ with queries earlier in the file handled first. This has
+ implications for merging, see the section called “Merging”.
+ See the section called “Generating the menus” for full details on
+ how to process <Include> and <Exclude> elements.
+
- <Exclude>
+ Any number of <Exclude> elements may appear below a
+ <Menu> element. The content of an <Exclude> element
+ is a list of matching rules, just as with an
+ <Include>. However, the desktop entries matched are
+ removed from the list of desktop entries included so far. (Thus
+ an <Exclude> element that appears before any
+ <Include> elements will have no effect, for example, as no
+ desktop entries have been included yet.)
+
- <Filename>
+ The <Filename> element is the most basic matching rule.
+ It matches a desktop entry if the desktop entry has the given
+ desktop-file id. See Desktop-File Id.
+
- <Category>
+ The <Category> element is another basic matching
+ predicate. It matches a desktop entry if the desktop entry has
+ the given category in its Categories field.
+
- <All>
+ The <All> element is a matching rule that matches
+ all desktop entries.
+
- <And>
+ The <And> element contains a list of matching rules.
+ If each of the matching rules inside the <And>
+ element match a desktop entry, then the entire
+ <And> rule matches the desktop entry.
+
- <Or>
+ The <Or> element contains a list of matching rules.
+ If any of the matching rules inside the <Or>
+ element match a desktop entry, then the entire
+ <Or> rule matches the desktop entry.
+
- <Not>
+ The <Not> element contains a list of matching rules. If
+ any of the matching rules inside the <Not> element matches
+ a desktop entry, then the entire <Not> rule does
+ not match the desktop entry. That is,
+ matching rules below <Not> have a logical OR relationship.
+
- <MergeFile>
+ Any number of <MergeFile> elements may be listed below a
+ <Menu> element, giving the name of another menu file to
+ be merged into this one. the section called “Merging”
+ specifies how merging is done. The root <Menu> of the
+ merged file will be merged into the immediate parent of the
+ <MergeFile> element. The <Name> element of the
+ root <Menu> of the merged file are ignored. If the
+ filename given as a <MergeFile> is not an absolute path,
+ it should be located relative to the location of the menu file
+ being parsed.
+
+ Duplicate <MergeFile> elements (that specify the same
+ file) are handled as with duplicate <AppDir>
+ elements (the last duplicate is used).
+
- <MergeDir>
+ Any number of <MergeDir> elements may be listed below a
+ <Menu> element. A <MergeDir> contains the name of a
+ directory. Each file in the given directory which ends in the
+ ".menu" extension should be merged in the same way that a
+ <MergeFile> would be. If the filename given as a
+ <MergeDir> is not an absolute path, it should be located
+ relative to the location of the menu file being parsed.
+ The files inside the merged directory are not merged in any
+ specified order.
+
+ Duplicate <MergeDir> elements (that specify the same
+ directory) are handled as with duplicate <AppDir>
+ elements (the last duplicate is used).
+
- <DefaultMergeDirs>
+ This element may only appear below <Menu>. The element has
+ no content. The element should be treated as if it were a list
+ of <MergeDir> elements containing the default merge
+ directory locations. When expanding <DefaultMergeDirs> to a
+ list of <MergeDir>, the default locations that are earlier
+ in the search path go later in the <Menu> so that they
+ have priority.
+
- <LegacyDir>
+ This element may only appear below <Menu>. The text
+ content of this element is a directory name. Each directory
+ listed in a <LegacyDir> element will be an old-style
+ legacy hierarchy of desktop entries, see the section called “Legacy Menu Hierarchies” for how to load such a
+ hierarchy. Implementations must not load legacy hierarchies that
+ are not explicitly specified in the menu file (because for
+ example the menu file may not be the main menu). If the
+ filename given as a <LegacyDir> is not an absolute path,
+ it should be located relative to the location of the menu file
+ being parsed.
+
+ Duplicate <LegacyDir> elements (that specify the same
+ directory) are handled as with duplicate <AppDir>
+ elements (the last duplicate is used).
+
+ The <LegacyDir> element may have one attribute,
+ prefix. Normally, given a <LegacyDir>
+ /foo/bar and desktop entry
+ /foo/bar/baz/Hello.desktop the desktop
+ entry would get a desktop-file id of Hello.desktop.
+ Given a prefix of boo-, it would instead be
+ assigned the desktop-file id boo-Hello.desktop.
+ The prefix should not contain path separator ('/') characters.
+
- <KDELegacyDirs>
+ This element may only appear below <Menu>. The element has
+ no content. The element should be treated as if it were a list
+ of <LegacyDir> elements containing the traditional desktop
+ file locations supported by KDE with a hard coded prefix of "kde-".
+ When expanding <KDELegacyDirs> to a list of <LegacyDir>, the
+ locations that are earlier in the search path go later in the
+ <Menu> so that they have priority.
+ The search path can be obtained by running kde-config --path apps
+
- <Move>
+ This element may only appear below <Menu>. The
+ <Move> element contains pairs of <Old>/<New>
+ elements indicating how to rename a descendant of the current
+ <Menu>. If the destination path already exists, the moved
+ menu is merged with the destination menu (see the section called “Merging” for details).
+
+ <Move> is used primarily to fix up legacy directories.
+ For example, say you are merging a <LegacyDir> with folder
+ names that don't match the current hierarchy; the legacy folder
+ names can be moved to the new names, where they will be merged
+ with the new folders.
+
+ <Move> may or may not be useful for implementing menu
+ editing, see the section called “Menu editing”.
+
+ Duplicate <Move> elements are merged as specified in the section called “Merging”. Note that duplicates (two moves of
+ the same path) can be detected easily because of the following
+ rule: a move must reside at the lowest possible point.
+
+ In other words, all moves have exactly one permissible location
+ in the <Menu> hierarchy. Implementations can trivially
+ detect violations of this rule: the <Old> and <New>
+ paths may never share a common prefix. Moving "Foo/Bar" to
+ "Foo/Baz" must be done with a <Move> element that's a
+ child of the "Foo" <Menu>, i.e. by moving "Bar" to "Baz", not
+ by moving "Foo/Bar" to "Foo/Baz".
+
- <Old>
+ This element may only appear below <Move>, and
+ must be followed by a <New> element. The content of both
+ <Old> and <New> should be a menu path
+ (slash-separated concatenation of <Name> fields, see
+ Menu path).
+ Paths are interpreted relative to the menu containing
+ the <Move> element.
+
- <New>
+ This element may only appear below <Move>, and must
+ be preceded by an <Old> element. The <New> element
+ specifies the new path for the preceding <Old> element.
+
- <Layout>
+ The <Layout> element is an optional part of this specification.
+ Implementations that do not support the <Layout> element should
+ preserve any <Layout> elements and their contents as far as
+ possible.
+ Each <Menu> may optionally contain a <Layout> element.
+ If multipe elements appear then only the last such element is relevant.
+ The purpose of this element is to offer suggestions for the presentation
+ of the menu.
+ If a menu does not contain a <Layout> element or if it contains
+ an empty <Layout> element then the default layout should be used.
+ The <Layout> element may contain <Filename>, <Menuname>,
+ <Separator> and <Merge> elements. The <Layout> element
+ defines a suggested layout for the menu starting from top to bottom.
+ References to desktop entries that are not contained in this
+ menu as defined by the <Include> and <Exclude> elements should
+ be ignored. References to sub-menus that are not directly contained in this
+ menu as defined by the <Menu> elements should be ignored.
+
- <DefaultLayout [show_empty="false"] [inline="false"] [inline_limit="4"] [inline_header="true"] [inline_alias="false"]>
+ The <DefaultLayout> element is an optional part of this specification.
+ Implementations that do not support the <DefaultLayout> element should
+ preserve any <DefaultLayout> elements and their contents as far as
+ possible.
+ Each <Menu> may optionally contain a <DefaultLayout> element
+ which defines the default-layout for the current menu and all its sub-menus.
+ If a menu has a <DefaultLayout> element then this will override
+ any default-layout specified by a parent menu.
+ The default-layout defines the suggested layout if a <Menu> element
+ does either not have <Layout> element or if it has an empty <Layout> element.
+ For explanations of the various attributes see the <Menuname> element.
+ If no default-layout has been specified then the layout as specified by the following
+ elements should be assumed:
+ <DefaultLayout show_empty="false" inline="false" inline_limit="4" inline_header="true" inline_alias="false"><Merge type="menus"/><Merge type="files"/></DefaultLayout>
+
- <Menuname [show_empty="..."] [inline="..."] [inline_limit="..."] [inline_header="..."] [inline_alias="..."]>
+ This element may only appear as a child of a <Layout> or <DefaultLayout>
+ menu. Its contents references an immediate sub-menu of the current menu as defined
+ with the <Menu> element, as such it should never contain a slash.
+ If no such sub-menu exists the element should be ignored.
+ This element may have various attributes, the default values are taken from the DefaultLayout key.
+ The show_empty attribute defines whether a menu that contains no desktop
+ entries and no sub-menus should be shown at all. The show_empty attribute
+ can be "true" or "false".
+ It may have an inline attribute that can be either "true" or "false".
+ If the inline attribute is "true" the menu that is referenced may be copied into the
+ current menu at the current point instead of being inserted as sub-menu of the current menu.
+ The optional inline_limit attribute defines the maximum number of entries that can be inlined.
+ If the sub-menu has more entries than inline_limit, the sub-menu will not be inlined.
+ If the inline_limit is 0 (zero) there is no limit.
+ The optional inline_title attribute defines whether an inlined menu should be preceeded with
+ a header entry listing the caption of the sub-menu.
+ The inline_title attribute can be either "true" or "false".
+ The optional inline_alias attribute defines whether a single inlined entry should adopt the
+ caption of the inlined menu. In such case no additional header entry will be added regardless
+ of the value of the inline_title attribute.
+ The inline_alias attribute can be either "true" or "false".
+ Example: if a menu has a sub-menu titled "WordProcessor" with a single entry "OpenOffice 4.2",
+ and both inline="true" and inline_alias="true" are specified then this would result in the
+ "OpenOffice 4.2" entry being inlined in the current menu but the "OpenOffice 4.2" caption
+ of the entry would be replaced with "WordProcessor".
+
- <Separator>
+ This element may only appear as a child of a <Layout> or <DefaultLayout>
+ menu. It indicates a suggestion to draw a visual separator at this point in the menu.
+ <Separator> elements at the start of a menu, at the end of a menu or that directly
+ follow other <Separator> elements may be ignored.
+
- <Merge type="menus"|"files"|"all"/>
+ This element may only appear as a child of a <Layout> or <DefaultLayout>
+ menu. It indicates the point where desktop entries and sub-menus that are not explicitly
+ mentioned within the <Layout> or <DefaultLayout> element are to be inserted.
+ It has a type attribute that indicates which elements should be inserted:
+ type="menus"
+ means that all sub-menus that are not explicitly mentioned should be inserted in
+ alphabetical order of their visual caption at this point.
+ type="files"
+ means that all desktop entries
+ contained in this menu that are not explicitly mentioned should be inserted in
+ alphabetical order of their visual caption at this point.
+ type="all" means that a mix of all sub-menus
+ and all desktop entries that are not explicitly mentioned should be inserted in
+ alphabetical order of their visual caption at this point.
+ Each <Layout> or <DefaultLayout> element shall have exactly one <Merge type="all">
+ element or it shall have exactly one <Merge type="files"> and exactly one
+ <Merge type="menus"> element. An excemption is made for a completely empty <Layout>
+ element which may be used to indicate that the default-layout should be used instead.
+
+
+ Sometimes two menu layouts need to be merged. This is done when folding in
+ legacy menu hierarchies (see the section called “Legacy Menu Hierarchies”) and also
+ for files specified in <MergeFile> elements. A common case is that
+ per-user menu files might merge the system menu file. Merging is also used
+ to avoid cut-and-paste, for example to include a common submenu in
+ multiple menu files.
+
+ Merging involves a base <Menu> and a merged <Menu>. The base
+ is the "target" menu and the merged <Menu> is being added to it. The
+ result of the merge is termed the "combined menu."
+
+ As a preparatory step, the goal is to resolve all files into
+ XML elements. To do so, traverse the entire menu tree. For each
+ <MergeFile>, <MergeDir>, or <LegacyDir> element, replace
+ the <MergeFile>, <MergeDir>, or <LegacyDir> element with
+ the child elements of the root <Menu> of the file(s) being
+ merged. As a special exception, remove the <Name> element from the
+ root element of each file being merged. To generate a
+ <Menu> based on a <LegacyDir>, see
+ the section called “Legacy Menu Hierarchies”.
+
+ Continue processing until no <MergeFile>, <MergeDir>, or
+ <LegacyDir> elements remain, taking care to avoid infinite loops
+ caused by files that reference one another.
+
+ Once all files have been loaded into a single tree, scan the tree
+ recursively performing these steps to remove duplicates:
+
+ Consolidate child menus. Each group of child <Menu>s with the same
+ name must be consolidated into a single child menu with that name.
+ Concatenate the child elements of all menus with the same name, in
+ the order that they appear, and insert those elements as the
+ children of the last menu with that name.
+ Delete all the newly empty <Menu> elements, keeping the
+ last one.
+
+ Expand <DefaultAppDirs> and <DefaultDirectoryDirs>
+ elements to <AppDir> and <DirectoryDir> elements.
+ Consolidate duplicate <AppDir>, <DirectoryDir>,
+ and <Directory> elements by keeping the last one.
+ For <Directory> elements that refer to distinct directory
+ entries, all of them should be kept - if the last one points
+ to a nonexistent file, the one before that can be used instead,
+ and so forth.
+
+ Resolve duplicate <Move> operations (with the same
+ origin path) by keeping the last one.
+
+ Recurse into each child <Menu>, performing this list of
+ steps for each child in order.
+
+
+ After recursing once to remove duplicates, resolve <Move> elements
+ for each menu starting with the top level and recursing into child menus.
+ So the deepest menus have their <Move> operations performed last.
+ Within each <Menu>, execute <Move> operations in the order
+ that they appear. If the destination path does not exist, simply relocate
+ the origin <Menu> element, and change its <Name> field to
+ match the destination path. If the origin path does not exist, do
+ nothing. If both paths exist, take the origin <Menu> element,
+ delete its <Name> element, and prepend its remaining child elements
+ to the destination <Menu> element.
+
+ If any <Move> operations affect a menu, then re-run the
+ steps to resolve duplicates in case any duplicates have been
+ created.
+
+ Finally, for each <Menu> containing a <Deleted> element which
+ is not followed by a <NotDeleted> element, remove that menu and all
+ its child menus.
+
+ Merged menu elements are kept in order because <Include> and
+ <Exclude> elements later in the file override <Include> and
+ <Exclude> elements earlier in the file. This means that if the user's
+ menu file merges the system menu file, the user can always override what
+ the system menu specifies by placing elements after the <MergeFile>
+ that incorporates the system file.
+
+ To prevent that a desktop entry from one party inadvertently cancels out
+ the desktop entry from another party because both happen to get the same
+ desktop-file id it is recommended that providers of desktop-files ensure that
+ all desktop-file ids start with a vendor prefix. A vendor prefix
+ consists of [a-zA-Z] and is terminated with a dash ("-"). Open Source
+ projects and commercial parties are encouraged to use a word or phrase,
+ preferably their name, as prefix for which they hold a trademark. Open Source
+ applications can also ask to make use of the vendor prefix of another open
+ source project (such as GNOME or KDE) they consider themselves affiliated
+ with, at the discretion of these projects.
+
+ For example, to ensure that GNOME applications start with a vendor prefix of "gnome-",
+ it could either add "gnome-" to all the desktop files it installs in
+ datadir/applications/ or it could
+ install desktop files in a datadir/applications/gnome
+ subdirectory. When including legacy menu hierarchies the prefix argument
+ of the <LegacyDir> element can be used to specify a prefix.
+
+ After merging the menus, the result should be a single menu layout
+ description. For each <Menu>, we have a list of directories where
+ desktop entries can be found, a list of directories where directory
+ entries can be found, and a series of <Include> and <Exclude>
+ directives.
+
+ For each <Menu> element, build a pool of desktop entries by
+ collecting entries found in each <AppDir> for the menu element. If
+ two entries have the same desktop-file id, the entry for the earlier (closer
+ to the top of the file) <AppDir> must be discarded. Next, add to the
+ pool the entries for any <AppDir>s specified by ancestor
+ <Menu> elements. If a parent menu has a duplicate entry (same
+ desktop-file id), the entry for the child menu has priority.
+
+ Next, walk through all <Include> and <Exclude> statements.
+ For each <Include>, match the rules against the pool of all desktop
+ entries. For each desktop entry that matches one of the rules,
+ add it to the menu to be displayed. For each <Exclude>, match
+ the rules against the currently-included desktop entries. For each
+ desktop entry that matches, remove it again from the menu.
+
+ Two passes are necessary, once for regular menus, and
+ once for <OnlyUnallocated> menus.
+
+ The result is a tree of desktop entries, of course.
+
+ Traditionally, menus were defined as a filesystem hierarchy, with each
+ filesystem directory corresponding to a submenu. Implementations of this
+ specification must be able to load these old-style hierarchies
+ as specified in this section.
+
+ The general approach is: the legacy hierarchy is converted into a
+ <Menu>, and then this menu layout is merged with the menu that
+ specified <LegacyDir>.
+
+ Desktop entries in the legacy hierarchy should be added to the pool of
+ desktop entries as if the <LegacyDir> were an
+ <AppDir>. Directory entries in the legacy hierarchy should be added
+ to the pool of directory entries as if the <LegacyDir> were a
+ <DirectoryDir>. This can be trivially implemented by adding
+ appropriate <AppDir> and <DirectoryDir> statements to the root
+ legacy <Menu>. There is one slight complexity, namely the
+ "prefix" attribute of <LegacyDir>.
+
+ The menu layout corresponds conceptually to the following, though actually
+ generating the XML is not necessary:
+
+ For each directory in the legacy hierarchy, a
+ <Menu> is created with the same <Name>
+ as the directory on disk.
+
+ This menu then contains an <Include> element that includes
+ each desktop entry in the directory. That is, it should have a
+
+ <Filename>Foo/Bar/foo.desktop</Filename>
+ for each desktop entry in the directory.
+
+ As a special exception, if a desktop entry in a directory contains
+ a Categories field, that desktop entry should
+ not be included in the legacy menu.
+ That is, no <Include> element should be generated for
+ the entry. This allows a desktop entry to be installed
+ in a legacy location but still work optimally with the
+ menu system specified in this document.
+
+ If the legacy directory contains a ".directory" file, then
+ a <Directory> element should be generated that points to said
+ ".directory" file.
+
+ Legacy desktop entries should not be assigned any
+ Categories fields if they didn't have them
+ already, except that all legacy entries should have the
+ "Legacy" category added to allow menu files to treat them
+ specially. (If the same directory is given as both
+ a <LegacyDir> and an <AppDir>, its desktop
+ entries should be labeled "Legacy" only if the <LegacyDir>
+ appears later in the file than the <AppDir>.)
+
+
+ For example, say we have the following legacy directory hierarchy:
+
+ Conceptually that is converted to the following <Menu>:
+
+ This <Menu> is then merged as if it were in a file
+ and loaded with <MergeFile>.
+
+ Remember, these are case-sensitive.
+ When using a category described in the list below it is strongly
+ recommended to also include the category listed under Related
+ Categories. If a category has multiple related categories the most
+ suitable related category should be included.
+
+
+
B. Registered OnlyShowIn Environments
+ Remember, these are case-sensitive. "KDE" not "kde" should be
+ used.
+
+
C. How to add your application to the menus
+ The short answer for third party applications is:
+
+ Install desktop entries to
+ datadir/applications/ for each menu
+ item. Please namespace the filename, as in "vendor-foo.desktop", or
+ use a subdirectory of
+ datadir/applications/ so you have
+ "vendor/foo.desktop." Please be sure all desktop entries are valid
+ (see the
+ desktop-file-utils package for a validation utility).
+
+ Install an XML menu file to sysconfdir/desktop/menus/applications-merged/ to add any submenus, if your desktop entries aren't already
+ included in some common categories.
+
+ Install any directory entries needed for your submenus to datadir/desktop-directories/, taking care to namespace and validate
+ the directory entries.
+
+
+ Also, at least for a good long while, installing a directory hierarchy to
+ the old GNOME/KDE specific locations such as /usr/share/applnk and
+ /usr/share/gnome/apps should work. There are two ways to support
+ both the old and new menu systems at the same time:
+
+ If you add a Categories line to the desktop
+ entries in the legacy hierarchy, implementations of this
+ specification will ignore their location in the legacy hierarchy,
+ and arrange them according to Categories instead.
+ This allows you to install a single desktop file that works in all
+ cases, though on the down side it's in a legacy location.
+
+ If you add the line OnlyShowIn=Old; to a desktop
+ entry, then old legacy implementations that ignore
+ OnlyShowIn will still show the desktop entry, but
+ implementations of this specification will not. Thus you can
+ add an "OnlyShowIn=Old;" entry to the legacy
+ hierarchy, and a new-style desktop entry to
+ datadir/applications/, and still get
+ only one entry in the menus.
+
+
+ To implement menu editing, the intent is that a per-user file is
+ created. The per-user file should specify a <MergeFile> with the
+ systemwide file, so that system changes are inherited. When the user
+ deletes a menu item, you add
+ <Exclude><Filename>foo.desktop</Filename></Exclude>. If
+ the user adds a menu item, you use
+ <Include><Filename>foo.desktop</Filename></Include>.
+
+ If the user moves a folder, you might try to use <Move> elements
+ to represent that, but it's tricky. (Move A/B/C to D/E/F, then move D/E
+ to D/G, note that D/E/F still contains A/B/C while only the original D/E
+ was moved to D/G.) In order to move a folder, you have to "fix up"
+ all moves that move things into the folder being
+ moved to instead move things into the folder's new location.
+
+ To delete a folder, simply append the <Deleted> element.
+
+ Menu editors probably need to do some kind of consolidation/compression
+ to avoid an XML tree that grows infinitely over time.
+
+ This glossary defines some of the terms used in this specification.
+
- Desktop entry
+ A desktop entry is a file with a name ending in the ".desktop"
+ extension which conforms to the desktop
+ entry specification. It describes a menu item, including
+ a name, an icon, and what to do when the item is selected.
+ Desktop entries are also known as ".desktop files."
+
- Desktop-File Id
+ The id to identify a desktop entry with.
+ For example, if /usr/share/applications is
+ specified as an <AppDir>, and /opt/fop
+ as a <LegacyDir> with a prefix of foo-
+ then
+ /usr/share/applications/foo/bar.desktop,
+ /usr/share/applications/foo-bar.desktop
+ and
+ /opt/fop/Settings/bar.desktop all have
+ the same desktop-file id foo-bar.desktop
+
- Directory entry
+ A directory entry is a file with a name ending in the ".directory"
+ extension which conforms to the desktop
+ entry specification. It describes gives a localized name and
+ an icon for a submenu.
+ Directory entries are also known as ".directory files."
+
- Menu path
+ A "menu path" is the path to a particular menu. Menu paths are
+ always "relative" so never start with a slash character.
+ The path to a menu is simply the <Name> of each parent
+ of the menu, followed by the <Name> of the menu itself.
+ For example, "Foo/Bar/Baz" is a valid menu path.
+
- Relative path
+ The canonical path to a directory entry, relative to the
+ <DirectoryDir> containing the
+ entry. For example, if /usr/share/desktop-directories is
+ specified as an <DirectoryDir>, the relative path to
+ /usr/share/desktop-directories/foo/bar.directory is
+ foo/bar.directory.
+