Provided by: desktop-profiles_1.4.9_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, XFCE (>= 4.2), ROX, GNUSTEP and
       UDE out of the box. Support for Gconf (i.e. Gnome) profiles is  present
       but  needs  a change to the default gconf configuration to be activated
       (see HOW IT WORKS below).

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

       Specifically each profile is associated with a set of requirements, and
       a  precedence  value. On X startup the Xsession.d script will check for
       each profile whether the requirements are met, and  then  activate  all
       those profiles whose requirements are met 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.

          As   the   default   system-wide   path   file   (/etc/gconf/<gconf-
          version>/path) currently doesn’t include the  generated  path  files
          you’ll    need    to    replace    it    with    one    that    does
          (/usr/share/doc/desktop-profiles/examples/path is a path file  which
          will  give  the same behaviour as the default gconf setup as long as
          no additional profiles are present).

       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.

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 2 directory (in which case directies 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://www.kde.org/areas/sysadmin/fsh.php)

          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://www.kde.org/areas/sysadmin   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/Standards/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/Standards. 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://xfce.org/~benny/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  directorys  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
          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),   profile-manager(1),   dh_installlisting(1),
       path2listing(1)