DESKTOP-PROFILES(7)					 Miscellaneous Information Manual				       DESKTOP-PROFILES(7)

NAME

       desktop-profiles - introduction and overview

DESCRIPTION

       Desktop-profiles  offers  a  standard  way  of managing the conditional activation of installed profiles (sets of configuration and/or data
       files) for the various Desktop Environments in Debian.

       It currently supports Freedesktop, KDE, Gconf (i.e Gnome), Xfce (>= 4.2), ROX, GNUSTEP and UDE.

HOW IT WORKS

       Each available profile has some metadata associated with it. On X startup an Xsession.d script is run that looks through the  metadata  for
       all profiles and activates profiles based on what it finds.

       Specifically  each profile is associated with a set of requirements, and a precedence value. On X startup the Xsession.d script will filter
       out those profiles whose requirements are not met, and then activate the remaining profiles in order of precedence.

       Exactly how a profile is activated depends on the profile kind (you don't need to know this in order to use this package):

       o  For KDE, Freedesktop, Xfce (>= 4.2), ROX, GNUSTEP and UDE activating profiles is done by setting environment variables: KDEDIRS for KDE,
	  XDG_CONFIG_DIRS  and XDG_DATA_DIRS for both Freedesktop and Xfce, CHOICESPATH for ROX, GNUSTEP_PATHLIST for GNUSTEP (usually initialized
	  from the various GNUSTEP_*_ROOT variables) and UDEdir for UDE. With the exception of UDEdir, which takes a  single  directory,  each	of
	  these variables takes a precedence ordered list of root-directories (of activated profiles).

       o  For  GConf profiles two user-specific path files are generated. One containing the activated mandatory "configuration sources", one con-
	  taining the default "configuration sources" that are activated.

       NOTE:
	  Environment variables will only be set if their value is different from the default value, and user-specific path files are only  gener-
	  ated if the systemwide gconf path file will include them. This to avoid unnecessary clutter.

       NOTE:
	  The  above  means  that  for Freedesktop, KDE, GNOME, Xfce (>= 4.2), GNUSTEP and ROX any number of profiles can be activated at the same
	  time. Whereas UDE can only activate 1 profiles at the time.

       NOTE:
	  By default the Xsession.d script will assume the metadata files are authoritive, meaning it will ignore any values already  assigned	to
	  the relevant environment variables.

       NOTE:
	  The default system-wide path contains a number of configuration sources not managed by desktop-profiles. In order to facilitate the man-
	  agement of all your configuration sources through desktop-profiles this package provides a script (/usr/sbin/path2listing) that looks at
	  your	current  gconf	configuration and adapts it so your configuration sources are all controlled by desktop-profiles (see the man page
	  for path2listing or the /usr/share/doc/destkop-profiles/README for more information on this).

INTERACTION WITH OTHER AGENTS ACTIVATING PROFILES

       Since profiles are activated through environment variables one issue is how desktop-profiles deals with the situation where those  environ-
       ment  variables	have already been set up by other agents (such an agent could be another script, or the user). Desktop-profiles has a per-
       sonality setting that determines how it handles such a situation:

       o  autocrat: assume desktop-profiles is the only agent allowed to touch the environment variables, and consequently ignore the contents	of
	  already set environment variables.

       o  rude: profiles added by desktop-profiles take precedence over profiles added by other agents.

       o  polite: profiles added by other agents take precedence over profiles added by desktop-profiles.

       o  sheep:  just	meekly	follow along with what the other agents have set, don't change anything (this essentially deactivates desktop-pro-
	  files).

       The default personality setting of desktop-profiles is polite.

WHERE TO FIND THE PROFILE METADATA

       The metadata is specified in .listing files that are placed in the /etc/desktop-profiles directory. The format of those files is  specified
       in the 'FORMAT OF .listing FILES'-section below.

       NOTE:  In order to ensure that packages containing .listing files don't run in to each other, packages should install such files as <packa-
	      gename>.listing, or <packagename>_<something>.listing (there's a debhelper script provided to help with that :)

FORMAT OF .listing FILES
       Each non-empty line in a .listing file is either a comment line, or line containing profile metadata.

       Comment lines start with '#' and are purely for human consumption, like empty lines they are ingored completely by the Xsession.d script.

       Lines containing profile metadata are made up of 6 fields separated by a semi-colon (';'). Where the meaning of the fields is as follows:

       o  1st field : Name of the profile, arbitrary, must be unique within each file, and may (but probably should not) be empty.

       o  2nd field : The kind of profile, must be set, must be one of: KDE, XDG_CONFIG, XDG_DATA, GCONF, ROX, GNUSTEP, or UDE.

       o  3th field:

	  Location of the root of the profile directory tree, may contain more then 1 directory (in which case	directories  should  be  separated
	  with spaces). Environment variables may be used when specifying root directories (e.g. $HOME/.extra_config).

	  Except  for  Gconf profiles, which use the this field to contain exactly one directive to be included in the generated path file (direc-
	  tives are either 'xml:(readonly|readwrite):<profile-root>', or 'include <some-path-file>' ).

       o  4th field : A Numeric precedence value for the profile, may be empty (which is treated as lowest possible precedence).

	  When 2 (or more) active profiles define a setup for the same thing, the value specified by the profile with the highest precedence value
	  is used (UDE will onlyuse values from the highest ranked profile).

       o  5th  field  : Space separated list of conditions that need to be met to activate the profiles (if more then 1 condition is specified all
	  conditions need to be met to activate the profile).

	  There are 3 different kinds of requirements:

	  1) <group>	  = user needs to be a member of <group>

	  2) !<group>	  = user mustn't be a member of <group>

	     (Note: '!' deactivates the profile completely)

	  3) $(<command>) = <command> needs to exit succesfully ($?=0)

	     (Where <command> is an arbitrary shell command)

       o  6th field : A description of what the profile is/does, may be empty.

	  Note that this basically boils down to a CSV-file using ';' as separator and allowing shell-style comments.

CREATING PROFILES

       o  KDE (through KDEDIRS):

	  Each profile directory is layed out according to the	KDE  file  system  hierarchy  (see  http://techbase.kde.org/KDE_System_Administra-
	  tion#File_System)

	  Config  files  in  the different profiles are merged (in case of conflicting keys, the value of the highest precedence profile is used).
	  For other files the highest precedence profile that contains the file supplies it.

	  Starting with kde 3.3. the kiosk framework can be used to lock settings down in the profiles, for all unlocked  settings  user-specified
	  values  are always used when available. (see http://techbase.kde.org/KDE_System_Administration for more info on the kiosk-framework, and
	  the format of the kde config files).

       o  Freedesktop (using XDG_CONFIG_DIRS and XDG_DATA_DIRS)

	  The 'Desktop base directory specification' defines the basic framework for using  profiles  (see  http://freedesktop.org/wiki/Specifica-
	  tions/basedir-spec).

	  The  actual contents of the profiles is filled in by things conforming to other freedesktop standards (e.g. the 'menu specification'). A
	  list of freedesktop standards (that are being worked on) can be found at http://freedesktop.org/wiki/Specifications. Most of these stan-
	  dards  are  still  under development and not (yet) widely supported. Eventually you can probably suspect support of at least KDE, GNOME,
	  ROX, and Xfce.

	  Xfce (>=4.2) specific settings can also be found in Freedesktop profile dirs (see the next section for details).

       o  Xfce (using XDG_CONFIG_DIRS and XDG_DATA_DIRS)

	  Starting from Xfce version 4.2. Xfce will completely adopt the freedesktop 'Desktop Base Directory Specification'. Placing any Xfce-only
	  settings  in	an  'xfce4'  subdirectory  of  the freedesktop profile directories (with the exception of xfce4-session, which will use an
	  'xfce4-session' subdirectory). A more complete description can be found at http://foo-projects.org/~benny/xfce/file-locations.html.

	  If two profiles contain the same config file, the one from the profile with the highest precedence is used.

	  Xfce versions prior to 4.2. don't support multiple config sets.

       o  ROX (through CHOICESPATH):

	  Each profile directory has one subdirectory for each app for which it provides settings. When a configuration value is needed  the  pro-
	  file directories are searched in order, first profile that contains the file supplies it.

       NOTE:
	  Programs  _may_ merge the files the different profiles. If the merging encounters conflicting values the one from the highest order pro-
	  file is used.

	  See http://rox.sourceforge.net/choices.html for a more detailed description.

       o  GNUSTEP (through GNUSTEP_PATHLIST)

	  Profiles in GNUSTEP parlance are called domains, and by default GNUSTEP will look in 4 domains (the location of which  is  indicated	by
	  the  GNUSTEP_USER_ROOT,  GNUSTEP_LOCAL_ROOT,	GNUSTEP_NETWORK_ROOT, and GNUSTEP_SYSTEM_ROOT variables). Though it is possible to specify
	  extra domains to use through the GNUSTEP_PATHLIST variable, it isn't often done as configuration files are currently only  searched  for
	  in the user domain.

	  For more information on GNUSTEP domains see http://www.gnustep.org/resources/documentation/User/GNUstep/filesystem.html

       o  UDE (through UDEdir):

	  UDE searches for configuration files in the following directories (first find is used):

	  1. $HOME/.ude/config

	  2. $UDEdir/config  (or in absence of $UDEdir in the install dir which is /usr/share/ude on debian)

	  3. If the configuration file is still not found, UWM takes the filename as it is (usually dereferencing any environment variables first)

       o  GNOME (using GConf 'Configuration Sources'):

	  Two  gconf  path  files are generated for each user on login: one with all the sources from activated profiles that have a higher prece-
	  dence then the gconf-user profile (which is in default.listing), and one containing the sources from activated  profiles  with  a  lower
	  precedence then the gconf-user profiles. Generated path files are put in /var/cache/desktop-profiles.

	  Each configuration source is structured like a simple hierarchical file system as follows:

	  -  Directories  correspond  to  applications	that  use  the	GConf repository, except for the ' schemas' directory which contains files
	  describing all of the preference keys.

	  - Subdirectories correspond to categories of preferences.

	  - Files list the preference keys in the directory, and contain information about the keys.

	  - Configuration Sources are searched in order for each value, first source that has the value (or is writeable in case of  storing  val-
	  ues) is used.

	  -> See the GNOME administration manual for a detailed explanation

FILES

       /etc/desktop-profiles/desktop-profiles.listing - Details the default settings for the various environments. By default the system-wide set-
       tings provided by the packager are given no precedence, which means they will be loaded after all  profiles  with  a  precedence  specified
       (which should be true for all profiles you create).

       /etc/X11/Xsession.d/20desktop-profiles_activateDesktopProfiles - Xsesssion.d script that activates the profiles

       /etc/default/desktop-profiles - File containing default settings for the scripts in this package.

AUTHOR

       This manual page was written by Bart Cornelis <cobaco@skolelinux.no>.

SEE ALSO

       list-desktop-profiles(1), update-profile-cache(1), profile-manager(1), dh_installlisting(1), path2listing(1)

desktop-profiles						   May 02, 2005 					       DESKTOP-PROFILES(7)