Provided by: desktop-profiles_1.4.31_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  authoritative,
          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 ignored 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 successfully ($?=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.

       ·  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.html

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

       ·  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), dh_installlisting(1), path2listing(1)