Provided by: desktop-profiles_1.4.15+nmu1ubuntu1_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.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)