From c15b9df59efac72ea80fb715bf2a9d7f7afd1bba Mon Sep 17 00:00:00 2001 From: Waldo Bastian Date: Fri, 1 Aug 2003 20:14:51 +0000 Subject: Be more verbose about the use of prefixes Use "desktop file id" instead of * Be more verbose about the use of prefixes * Use "desktop file id" instead of "relative path" --- menu/menu-spec.xml | 113 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 34 deletions(-) (limited to 'menu') diff --git a/menu/menu-spec.xml b/menu/menu-spec.xml index d48e2aa..d348c49 100644 --- a/menu/menu-spec.xml +++ b/menu/menu-spec.xml @@ -4,15 +4,15 @@
Desktop Menu Specification - Version 0.4 - 31 May 2003 + Version 0.5 + 31 July 2003 Waldo Bastian
- waldo@kde.org + bastian@kde.org
@@ -298,23 +298,39 @@ entries: Categories and 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 relative path (see ). + by their desktop-file id (see ). + 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 relative paths. + 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. An <AppDir> should be recursively - scanned, finding all desktop entries below the given directory. - Only files ending in ".desktop" should be used, other files are - ignored. + file being parsed. Duplicate <AppDir> elements (that specify the same @@ -514,11 +530,7 @@ entries: Categories and The <Filename> element is the most basic matching rule. It matches a desktop entry if the desktop entry has the given - relative path. Absolute paths must not be used, - and relative paths must be the canonical form used to reference - a desktop entry in the pool of desktop entries (they can't - contain ".." or anything of that nature, and can't contain - extra "/" characters). See . + desktop-file id. See . @@ -658,13 +670,10 @@ entries: Categories and prefix. Normally, given a <LegacyDir> /foo/bar and desktop entry /foo/bar/baz/Hello.desktop the desktop - entry would be included as - baz/Hello.desktop. Given a prefix of - boo-, it would instead be loaded as - boo-Hello.desktop. In other words, if a - prefix is present it replaces the relative path to the desktop - or directory entry. The prefix may contain path separator ('/') - characters. + 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. @@ -675,12 +684,11 @@ entries: Categories and 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. When expanding - <KDELegacyDirs> to a list of <LegacyDir>, the + 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. - [FIXME what are the exact <LegacyDir prefix="???"> that - this expands to?] + The search path can be obtained by running kde-config --path apps @@ -852,6 +860,26 @@ entries: Categories and 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. + @@ -866,11 +894,11 @@ entries: Categories and 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 relative path, the entry for the earlier (closer + 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 - relative path), the entry for the child menu has priority. + desktop-file id), the entry for the child menu has priority. Next, walk through all <Include> and <Exclude> statements. @@ -1465,6 +1493,23 @@ entries: Categories and + 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 @@ -1493,12 +1538,12 @@ entries: Categories and Relative path - The canonical path to a desktop or directory entry, relative to the - <AppDir> or <DirectoryDir> containing the - entry. For example, if /usr/share/applications is - specified as an <AppDir>, the relative path to - /usr/share/applications/foo/bar.desktop is - foo/bar.desktop. + 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. -- cgit v1.2.3-70-g09d2