Provided by: desktop-profiles_1.4.22_all bug

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):

       •  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).

       •  For GConf profiles two user-specific path  files  are  generated.  One  containing  the
          activated  mandatory "configuration sources", one containing 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 generated 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  management 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 environment variables have already been set
       up by other agents (such an agent could be another script, or the user).  Desktop-profiles
       has a personality setting that determines how it handles such a situation:

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

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

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

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

       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   <packagename>.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:

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

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

       •  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    (directives    are    either
          ´xml:(readonly|readwrite):<profile-root>´, or ´include <some-path-file>' ).

       •  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).

       •  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)

       •  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

KDE (through KDEDIRS):

          Each  profile  directory  is  layed out according to the KDE file system hierarchy (see
          http://techbase.kde.org/KDE_System_Administration#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).

       •  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/Specifications/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  standards  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).

       •  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.

       •  ROX (through CHOICESPATH):

          Each profile directory has  one  subdirectory  for  each  app  for  which  it  provides
          settings.  When a configuration value is needed the profile 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 profile is used.

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

       •  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.htmlUDE (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)

       •  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  precedence  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 values) 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 settings 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)