Commits

edgimar committed dc15da4

- added new keys, grouped different sections, marked some keys deprecated

  • Participants
  • Parent commits 0b2d58a

Comments (0)

Files changed (1)

File xdg_autostart_spec.org

 #+TITLE: Desktop Application Autostart Specification
-#+AUTHOR: John Palmieri <johnp@redhat.com>,\\ Kévin Ottens <ervin@ipsquad.net>, Renato Caldas <seventhguardian_@hotmail.com>,\\ Rodrigo Moya <rodrigo@gnome-db.org>, Waldo Bastian <bastian@kde.org>
-#+DATE: version 0.5
+#+AUTHOR: Mark Edgington <edgimar@gmail.com>, John Palmieri <johnp@redhat.com>, Kévin Ottens <ervin@ipsquad.net>, Renato Caldas <seventhguardian_@hotmail.com>, Rodrigo Moya <rodrigo@gnome-db.org>, Waldo Bastian <bastian@kde.org>
+#+DATE: version 0.6
 
 * Introduction
 This DRAFT document defines a method for automatically starting applications during the startup of a desktop environment and after mounting a removable medium.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
 * Autostart Of Applications During Startup
-By placing an application's .desktop file in one of the Autostart directories the application will be automatically launched during startup of the user's desktop environment after the user has logged in.
+By placing an application's .desktop file in one of the Autostart directories, the application will be automatically launched during startup of the user's desktop environment after the user has logged in.
 
 ** Autostart Directories
 The Autostart Directories are =$XDG_CONFIG_DIRS/autostart= as defined in accordance with the [[http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html#referencing]["Referencing this specification"]] section in the [[http://standards.freedesktop.org/basedir-spec/]["desktop base directory specification"]].
 Example: If =$XDG_CONFIG_HOME= and =$XDG_CONFIG_DIRS= are not set and the two files =/etc/xdg/autostart/foo.desktop= and =~/.config/autostart/foo.desktop= exist, then only the file =~/.config/autostart/foo.desktop= will be used because =~/.config/autostart/= is more important than =/etc/xdg/autostart/=.
 
 * Application .desktop Files
-An application .desktop file must have the format as defined in the [[http://standards.freedesktop.org/desktop-entry-spec/]["Desktop Entry Specification"]].  All keys should be interpreted as defined with the following exceptions in order to take into account that the .desktop files in an autostart directory are not shown in a menu.
-** =Hidden= Key
-When the .desktop file has the =Hidden= key set to true, the .desktop file MUST be ignored. When multiple .desktop files with the same name exist in multiple directories, then only the =Hidden= key in the most important .desktop file must be considered:  if it is set to true, all .desktop files with the same name in the other directories MUST be ignored as well.
+An application .desktop file must have the format as defined in the [[http://standards.freedesktop.org/desktop-entry-spec/]["Desktop Entry Specification"]].  All keys except for the keys described in this document (the one you are now reading) should be interpreted as defined in the Desktop Entry Specification.  Furthermore, it should be understood that, in contrast to the ordinary usage of .desktop files to make application names and/or icons to appear in a menu or in a file-manager window, a .desktop file that exists within one of the Autostart directories is used primarily to determine whether an application will automatically start or not, and has no influence over the application's appearance or the lack thereof in menus or file-manager windows.
 
-** =OnlyShowIn= and =NotShowIn= Keys
+** =AutostartSpecVersion= Key
+For any version of the autostart specification newer than version 0.5, the =AutostartSpecVersion= SHOULD be specified.  If the .desktop file contains no keys specific to autostart specifications newer than version 0.5, the =AutostartSpecVersion= MAY be specified.
+
+Example: =AutostartSpecVersion=0.6=
+
+If an =AutostartSpecVersion= key exists, then the corresponding specification version should be followed.
+# this is fairly stupid.  While it you can't enforce that a spec version is followed, you should be able to say that a specific spec version should be followed if possible.  The problem is that if a newer spec version undoes what a previous spec version specifies, then this is big mess.  The question is whether a specversion key makes sense or is necessary.  You should be able to infer the spec version based on the existence or absence of specific keys.
+
+** =TryExec= Key
+A .desktop file with a non-empty =TryExec= field MUST NOT be autostarted if the value of the =TryExec= key does NOT match with an installed executable program. The value of the =TryExec= field may either be an absolute path or the name of an executable without any path components. If the name of an executable is specified without any path components, then the =$PATH= environment is searched to find a matching executable program.
+
+** Session-related keys
+When starting a specific desktop environment (DE) (e.g. Gnome, KDE, LXDE, XFCE), the DE may be configured to run under a specific /session/ which influences various characteristics of the DE (e.g. default behavior, appearance, started applications, etc.).  For a single user, a DE MAY allow the creation of multiple sessions which differ from each other, each having a unique session-name.  If a DE is started without a specific session-name, the session-name of "<DE_NAME>-default" is to be used (e.g. "Gnome-default").  Several of the following keys take a /session-name-list/ as their value, which is a semicolon-separated list of DE session-names.
+*** =AutostartDefaultPolicy= Key
+In the case that there is no matching session-name in the =AutostartEnabledFor= or =AutostartDisabledFor= lists, then the =AutostartDefaultPolicy= key specifies a default policy regarding whether an application should be automatically started or not, and can take on either the value =true= (i.e. the application should be started by default) or =false= (i.e. the application should not be started by default).  It is up to the DE to determine whether or not it will respect this default policy.  Typically this policy will be specified in the system-wide .desktop file by a software package's maintainer, but it can of course be overridden by a .desktop file in a user's local autostart directory (e.g. =~/.config/autostart=).
+
+Example: =AutostartDefaultPolicy=false=
+
+*** =AutostartEnabledFor= Key
+ The =AutostartEnabledFor= key specifies a session-name-list for which the .desktop file is to be considered /enabled/ (i.e. the application specified in the .desktop file MUST be loaded by the DE when it is running under a session having one of the session-names specified in this list).
+
+Example: =AutostartEnabledFor=Gnome-default;LXDE-work;LXDE-home=
+
+*** =AutostartDisabledFor= Key
+The =AutostartDisabledFor= key specifies a session-name-list for which the .desktop file is to be considered /disabled/ (i.e. the application specified in the .desktop file MUST NOT be loaded by the DE when it is running under a session having one of the session-names specified in this list).  In the case where a specific session-name is specified in both the =AutostartDisabledFor= and =AutostartEnabledFor= lists, then the application MUST NOT be loaded by the DE for when running under the session having this name.
+
+Example: =AutostartDisabledFor=LXDE-kiosk;xmonad-default=
+
+*** =HiddenDefaultPolicy= Key
+In the case that there is no matching session-name in the =HiddenFor= list, then the =HiddenDefaultPolicy= key specifies a default policy regarding whether or not an application should be hidden within a session-editing program, and can take on either the value =true= (by default, hide the application) or =false= (by default, show the application).  Typically this policy will be specified in the system-wide .desktop file by a software package's maintainer, but it can of course be overridden by a .desktop file in a user's local autostart directory (e.g. =~/.config/autostart=).  It is up to the author of a given session-editor program to determine whether or not the program will respect this default policy.  
+
+Example: =HiddenDefaultPolicy=true=
+
+*** =HiddenFor= Key
+The =HiddenFor= key specifies a session-name-list for which the .desktop file is to be considered /hidden/.  The value of this key influences the behavior of session-editor programs (i.e. programs that allows the user to select which applications should and should not be started for a given session).  If the session-name of a user's currently running session is found in the =HiddenFor= session-name-list, the application specified in the .desktop file SHOULD NOT be visible to the user when choosing which applications will or will-not autostart, except when made visible (or grayed out) by a non-default "advanced" mode offered by the session-editor program.
+
+Whether an application is hidden or not has no influence over whether it will or will not be autostarted.  Autostarting is affected by the =AutoStart*= keys.
+
+Example: =HiddenFor=XFCE-home;KDE-default=
+
+** Deprecated Keys
+The following keys should not be used in .desktop files unless necessary for backward compatibility with DEs which don't recognize the =HiddenFor= and =HiddenDefaultPolicy= keys (introduced in version 0.6 of the Autostart specification).  If an application is able to recognize any non-deprecated keys of this specification, and there is a conflict between any of the following keys and explicitly set non-deprecated keys, the non-deprecated keys are to take priority / effect over the deprecated ones.
+*** =Hidden= Key
+When the .desktop file has the =Hidden= key set to =true=, the .desktop file MUST be ignored. When multiple .desktop files with the same name exist in multiple directories, then only the =Hidden= key in the most important .desktop file must be considered:  if it is set to =true=, all .desktop files with the same name in the other directories MUST be ignored as well.
+*** =OnlyShowIn= and =NotShowIn= Keys
 The =OnlyShowIn= entry may contain a list of strings identifying the desktop environments that MUST autostart this application, all other desktop environments MUST NOT autostart this application.
 
 The =NotShowIn= entry may contain a list of strings identifying the desktop environments that MUST NOT autostart this application, all other desktop environments MUST autostart this application.
 
 Only one of these keys, either =OnlyShowIn= or =NotShowIn=, may appear in a single .desktop file.
 
-** =TryExec= Key
-A .desktop file with a non-empty =TryExec= field MUST NOT be autostarted if the value of the =TryExec= key does NOT match with an installed executable program. The value of the =TryExec= field may either be an absolute path or the name of an executable without any path components. If the name of an executable is specified without any path components, then the =$PATH= environment is searched to find a matching executable program.
-
 * Implementation Notes
-If an application autostarts by having a .desktop file installed in the system wide autostart directory, an individual user can disable the autotomatic start of this application by placing a .desktop file of the same name in the personal autostart directory which contains the key =Hidden=true=.
+# this doesn't *absolutely* disable it ; only if the DE follows this policy. -- should the policy be REQUIRED?  Or should there be a more absolute value that this key can take, like "never_start".
+If an application autostarts by having a .desktop file installed in the system wide autostart directory, an individual user can disable the autotomatic start of this application by placing a .desktop file of the same name in the personal autostart directory which contains the key =AutostartDefaultPolicy=false=.
 
 * Autostart Of Applications After Mount
-When a desktop environment mounts a new medium, the medium may contain an Autostart file that can suggest to start an application or an Autoopen file that can suggest to open a specific file located on the medium.
+# there is nothing here that specifies what the Autostart / Autoopen file should look like -- is its format the same as a .desktop file?  Does it just contain a single file-name?
+When a desktop environment mounts a new medium, the medium may contain an /Autostart/ which specifies a suggested application to start, or an /Autoopen/ file which specifies a suggested application-file to load with the default application associated with this type of file.
 
 ** Autostart Files
 When a new medium is mounted the root directory of the medium should be checked for the following Autostart files in order of precendence: =.autorun=, =autorun=, =autorun.sh=.  Only the first file that is present should be considered.
 
 When an Autostart file has been detected and the user has confirmed its execution, the autostart file MUST be executed with the current working directory (CWD) set to the root directory of the medium.
 
-* Autoopen Files
+** Autoopen Files
 When a new medium is mounted and a) the medium does not contain an Autostart file, or b) a policy to ignore Autostart files is in effect, then the root directory of the medium should be checked for the following Autoopen files in order of precedence: =.autoopen=, =autoopen=.  Only the first file that is present should be considered.
 
 The desktop environment MAY ignore Autoopen files altogether based on policy set by the user, system administrator, or vendor.