Wed Oct 9 15:32:20 2002 Owen Taylor <otaylor@redhat.com>

        * xsettings.xml: Add the spec (prior to converting
        to DocBook XML)

2 files changed, 376 insertions, 0 deletions

diff --git a/xsettings/ChangeLog b/xsettings/ChangeLog
index 141a909..2bcc683 100644
--- a/xsettings/ChangeLog
+++ b/xsettings/ChangeLog
@@ -1,3 +1,8 @@
+Wed Oct  9 15:32:20 2002  Owen Taylor  <otaylor@redhat.com>
+
+	* xsettings.xml: Add the spec (prior to converting
+	to DocBook XML)
+
 Tue Oct  8 19:19:37 2002  Owen Taylor  <otaylor@redhat.com>
 
 	* xsettings-common.c (xsettings_setting_free): Fre
diff --git a/xsettings/xsettings.xml b/xsettings/xsettings.xml
new file mode 100644
index 0000000..81e901b
--- /dev/null
+++ b/xsettings/xsettings.xml
@@ -0,0 +1,371 @@
+<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+]>
+<article id="index">
+  <artheader>
+    <title>XSETTINGS - cross toolkit configuration proposal</title>
+    <releaseinfo>Version 0.5</releaseinfo>
+    <date>19 March 2001</date>
+    <authorgroup>
+      <author>
+	<firstname>Owen</firstname>
+	<surname>Taylor</surname>
+	<affiliation>
+	  <address>
+	    <email>otaylor@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
+    </authorgroup>
+  </artheader>
+
+  <sect1 id="goals">
+    <title>Goals</title>
+    <para>
+      The intent of this specification is to specify a mechanism to
+      allow the configuration of settings such as double click timeout,
+      drag-and-drop threshold, and default foreground and background colors
+      for all applications running within a desktop. The mechanism should:
+    </para>
+    <simplelist>
+      <member>allow for instant updates to be propagated across all
+      applications at   runtime</member>
+      <member>perform well, even for remote applications.</member>
+    </simplelist>
+    <para>
+      It is not intended:
+    </para>
+    <simplelist>
+      <member>for the storage of application-specific data</member>
+      <member>to be able to store large amounts of data</member>
+      <member>to store complex data types (other than as
+      strings)</member>
+    </simplelist>
+  </sect1>
+  <sect1 id="existing">
+    <title>Existing Systems</title>
+    <para>
+      The existing systems in this area are the Xrm database, and various
+      other configuration database systems, mostly specific to particular
+      desktops. (The kde configuration system, gnome-config, GConf,
+      libproplist, etc.)
+    </para>
+    <para>
+      The Xrm database is tempting to use for this purpose since it is
+      very well established and has a universally deployed existing
+      implementation. However, it has various defects, that make it
+      not suitable for this purpose.
+    </para>
+    <itemizedlist>
+      <listitem>
+	<para>
+	  The Xrm database merges information from various sources - the
+	  ~/.Xdefaults file on the root window, and a property on the root
+	  window. This means that to programatically configure the Xrm
+	  database in response to a GUI config tool is difficult and
+	  unreliable.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  The Xrm database was not designed for on-the-fly changing of
+	  settings.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  The Xrm database stores all information in a single text
+	  property on the root window. This makes it difficult to
+	  determine what settings have changed; it is necessary to parse
+	  the property and do string comparisons.
+	</para>
+	<para>
+	  Additionally, most systems have a large amount of application
+	  specific information in the Xrm database, which further slows
+	  down notification of changes.
+	</para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      Other configuration databases are more designed for this
+      task. However, they are sophisticated systems that are not easily
+      reimplementable. Also, picking one would mean difficulties
+      integrating with other desktops that use different systems.
+    </para>
+    <para>
+      It is our contention that a system designed specifically for
+      configuration of a small number of settings being changed at
+      runtime can, compared to a more general existing system:
+    </para>
+    <simplelist>
+      <member>Be easier to bridge onto each systems native configuration
+	mechanism.</member>
+      <member>Be easier to implement in whatever language/library combination
+	people want to use.</member>
+      <member>Be more efficient.</member>
+    </simplelist>
+  </sect1>
+  <sect1 id="client-behavior">
+    <title>Client behavior</title>
+    <para>
+      On startup, each client that should identify the settings window by
+      calling XGetSelectionOwner() for the _XSETTINGS_S[N] selection and select
+      for notification on the settings window by calling XSelectInput()
+      with a mask of StructureNotifyMask|PropertyChangeMask.
+    </para>
+    <para>
+      To prevent race conditions a client MUST grab the
+      server while performing these operations using XGrabServer().
+    </para>
+    <para>
+      If there is no owner of the _XSETTINGS_S[N] selection, the client can
+      determine when an owner is established by listening for client
+      messages sent to root window of the screen with type MANAGER. (See
+      section 2.8, Manager Selections of the ICCCM.) The format of this
+      message is:
+    </para>
+    <programlisting>
+ event-mask:   StructureNotify
+ event:        ClientMessage
+ type:         MANAGER
+ format:       32
+ data[0]:      timestamp
+ data[1]:      _XSETTINGS_S[N] (atom)
+ data[2]:      New owner of the selection
+ data[3]:      0 (reserved)
+    </programlisting>
+    <para>
+      The client can then proceed to read contents of the _XSETTINGS_SETTINGS
+      property from the settings window and interpret according to 
+      the information in the "_XSETTINGS_SETTINGS Format" section of this 
+      document.
+    </para>
+    <para>
+      Clients must trap X errors when reading the _XSETTING_SETTINGS property
+      because it is possible that the selection window may be destroyed
+      at any time.
+    </para>
+    <para>
+      When the client is notified that the settings window has been
+      destroyed or discovers that the selection window has been destroyed,
+      it should reset all settings to their default values and then proceed
+      as on initial startup. [ See rational section ]
+    </para>
+    <para>
+      When a client receives a PropertyChangeNotify event for the window
+      it should reread the _XSETTING_SETTINGS property. It can use
+      the 'serial' field to tell what fields have been changed. The
+      client must parse the entire property and read in all new values
+      before taking action on changed settings such as notifying listeners
+      for those settings to avoid using a mix of old and new data.
+    </para>
+  </sect1>
+  <sect1 id="format">
+    <title>_XSETTINGS_SETTINGS Format</title>
+    <para>
+    The _XSETTINGS_SETTINGS property is of form 8 and type _XSETTINGS_SETTINGS.
+The contents are a
+    </para>
+    <programlisting>
+ 1	CARD8    byte-order
+ 3               unused
+ 4      CARD32   SERIAL
+ 4      CARD32   N_SETTINGS
+    </programlisting>
+    <para>
+Followed by N_SETTINGS settings records, which have a header:
+    </para>
+    <programlisting>
+ 1      SETTING_TYPE  type
+ 1                    unused
+ 2      n             name-len
+ n      STRING8       name
+ P                    unused, p=pad(n)
+ 4      CARD32        last-change-serial
+    </programlisting>
+    <para>
+Where SETTING_TYPE is
+    </para>
+    <programlisting>
+ 0  XSettingsTypeInteger
+ 1  XSettingsTypeString
+ 2  XSettingsTypeColor
+    </programlisting>
+    <para>
+followed by the body. If TYPE = XSettingsTypeString  the body is:
+    </para>
+    <programlisting>
+ 4      n             value-len
+ n      STRING8       value
+ P                    unused, p=pad(n)
+    </programlisting>
+
+    <para>
+If TYPE == XSettingsTypeInteger, then the body is:
+    </para>
+    <programlisting>
+ 4      INT32         value
+    </programlisting>
+
+    <para>
+      If TYPE == XSettingsTypeColor, then the body is:
+    </para>
+    <programlisting>
+ 2      CARD16        red
+ 2      CARD16        blue
+ 2      CARD16        green
+ 2      CARD16        alpha
+    </programlisting>
+    <para>
+If the setting does not need the alpha field, it should
+be set to 65535.
+    </para>
+    <para>
+      Setting names must be confined to the ascii characters:
+      </para>
+    <programlisting>
+ 'A'-'Z' 'a'-'z' '0'-'9' '_' and '/'
+    </programlisting>
+    <para>
+      With the additional restrictions that '/' cannot appear in
+      the leading or trailing position, that two occurences of
+      '/' cannot be consecutive, and that the first character
+      of the name, and and the first character after a slash
+      cannot be one of '0'-'9'. Names may not be empty.
+    </para>
+    <para>
+      So,
+    </para>
+    <programlisting>
+ "GTK/colors/background0"
+ "_background"
+ "_111"
+    </programlisting>
+    <para>
+      are legitimate names, while
+    </para>
+    <programlisting>
+ "/"
+ "_background/"
+ "GTK//colors"
+ ""
+    </programlisting>
+    <para>
+      Are not legitimate names.
+    </para>
+    <para>
+      The names, types, contents, and default values of standard settings
+      will be separately agreed upon.
+    </para>
+
+    <para>
+      Names beginning with 'Net/' and case variants of that string are
+      reserved and must not be used without prior agreement.
+    </para>
+    <para>
+      The 'serial' field and and the 'last-change-serial' field of the each
+      settings record can be used to tell which settings have changed since
+      the last time a client retrieved the _XSETTINGS_SETTINGS property. Each
+      time the client retrieves the contents of the _XSETTINGS_SETTINGS
+      property it should store the contents of the 'serial' field. When
+      it next retrieves the property, any settings whose 'last-change-serial'
+      is greater than the stored value.
+    </para>
+
+    <para>
+      (Careful clients will make provisions for wrap-around of the serial
+      field. This is, however, not expected to happen in practice.)
+    </para>
+  </sect1>
+  <sect1 id="manager-behavior">
+    <title>Settings Manager behavior</title>
+    <para>
+      The _XSETTING_S[N] selection is managed as a manager selection
+      according to section 2.8 of the ICCCM and the handling of the
+      selections window, the _XSETTING_S[N] window and MANAGER client
+      messages must conform to that specification.
+    </para>
+    <para>
+      The settings manager changes the contents of the _XSETTINGS_SETTINGS 
+      property of the root window whenever the source it derives them
+      from changes, taking care to increment the 'serial' field at each
+      increment and set the 'last-change-serial' fields appropriately.
+    </para>
+  </sect1>
+  <appendix id="rational">
+    <title>Rational and Discussion</title>
+    <para>
+      The reasons why an existing configuration mechanism, and in particular,
+      the Xrm database, was not used is discussed above. Various other
+      design decisions are discussed below:
+    </para>
+    <formalpara>
+      <title>Why aren't the contents of the property stored in XML?</title>
+      <para>
+	The data format is designed to be space efficient and to be easily
+	and efficiently parsed with minimal code. These are not things
+	XML does well. Flexibility of structure, things that XML
+	does well are not needed here. If needed, XML can be used for
+	the contents of individual settings.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Why is the settings property screen specific?</title>
+      <para>
+	While most settings are expected to be shared across all screens
+	of a display, some settings, such as font sizes will be screen
+	specific, and it is considered easier to let the settings manager
+	propagate shared resources across screens then to have both
+	screen-specific and screen-independent resources.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Why does there need to be a "settings manager" process
+      running?</title>
+      <para>
+	Having a process always present as the owner of the _XSETTING
+	selection ensures that there are no race conditions and is
+	simpler than trying to create a locking mechanism that can
+	work without a persistant process. It is also expected that to
+	properly handle notification of changes to the stored
+	properties most desktops will want a process running to watch
+	for changes in any case. In cases of tight resource usage, the
+	settings manager can be combined with some other function,
+	such as the window manager or session manager.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Why use a single property for all settings?</title>
+      <para>
+	Using a single property has several advantages. First, retrieving
+	all settings takes only a single round-trip to the server instead
+	of a round-trip for each settings. Second, it means that when
+	multiple settings can be changed at once, only a single notification
+	is received by clients, and clients will see interrelated properties
+	changed in an atomic fashion.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>Why is the _XSETTINGS_SETTINGS property stored in the endianess
+	of the manager instead of a neutral endianness?</title>
+      <para>
+	This conforms to the way many other X mechanisms work. The main reason
+	for doing it this way is to save conversions for the common case when
+	the client and manager are on machines of the same endianness.
+      </para>
+    </formalpara>
+    <formalpara>
+      <title>When the settings manager exits, why should clients reset the 
+	values to the default settings instead of keeping the current
+	settings?</title>
+      <para>
+	Resetting the settings to the default values is preferred to
+	maintaining the current values because it makes sure that all programs
+	on the desktop have consistent values for settings whether they were 
+	started before or after the settings manager exited. It is not
+	expected that changes in the current settings manager will occur
+	very often.
+      </para>
+    </formalpara>
+  </appendix>
+</article>
+