Provided by: desktop-profiles_1.4.14_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://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  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
          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),  profile-manager(1),
       dh_installlisting(1), path2listing(1)