WIPdocs-consolidation

5 files changed, 338 insertions, 1 deletions

diff --git a/docs/reference/tmpl/xfconf-channel.sgml b/docs/reference/tmpl/xfconf-channel.sgml
index 44b5451..bf16414 100644
--- a/docs/reference/tmpl/xfconf-channel.sgml
+++ b/docs/reference/tmpl/xfconf-channel.sgml
@@ -40,6 +40,11 @@ configuration keys with the same names.
 
 </para>
 
+<!-- ##### ARG XfconfChannel:is-singleton ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG XfconfChannel:property-base ##### -->
 <para>
 
diff --git a/docs/reference/xfconf-backends.xml b/docs/reference/xfconf-backends.xml
new file mode 100644
index 0000000..46f72fc
--- /dev/null
+++ b/docs/reference/xfconf-backends.xml
@@ -0,0 +1,251 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<article id="xfconf-backends" lang="en">
+  <sect1 id="xfconf-backends-s">
+    <title>Configuration Backends</title>
+
+    <para>
+      Xfconf backends act as the actual configuration store.  A backend might
+      write flat files to disk, XML files to disk, rows to a relational
+      database, entries to an LDAP server, or any other possible mechanism
+      desired to persistently store the data.
+    </para>
+
+    <para>
+      A backend must implement the <link linkend="XfconfBackendInterface">XfconfBackend
+      interface</link>, which is described in the API documentation.
+    </para>
+
+    <para>
+      The backend will have to deal with a variety of data types.  While some
+      of these types are wrapped directly in the client library (e.g.,
+      xfconf_channel_set_uint64()), users of the library can also set other,
+      semi-arbitrary types, as well as array types.
+    </para>
+
+    <para>
+      So, the backend must be able to understand the following GTypes:
+
+      <programlisting>
+        G_TYPE_STRING
+        G_TYPE_UCHAR
+        G_TYPE_CHAR
+        G_TYPE_UINT
+        G_TYPE_INT
+        G_TYPE_UINT64
+        G_TYPE_INT64
+        G_TYPE_FLOAT
+        G_TYPE_DOUBLE
+        G_TYPE_BOOLEAN
+      </programlisting>
+
+      Note about 16-bit values: dbus-glib does not support sending 16-bit signed
+      and unsigned integers over D-Bus, even though libdbus does.  For convenience,
+      libxfconf will take any 16-bit values it receives and convert them into
+      32-bit values before sending them to the daemon.  From the daemon/backend
+      point of view, 16-bit values are simply not supported.
+    </para>
+
+    <para>
+      In addition, the backend must be able to handle arrays of arbitrary
+      types from the above list.  A single array may hold multiple values
+      of the same type, or of different types.  Because of this, an array is
+      sent over the bus as a GValue which holds a GPtrArray which holds an
+      array of GValues (which of course hold the actual values).  The GType
+      of each value in the array must be checked, of course, as the array
+      elements may be of different types.
+    </para>
+
+  </sect1>
+
+  <sect1 id="xfconf-backend-perchannel-xml">
+    <title>Xfconf Perchannel-XML Backend</title>
+
+    <para>
+       The Per-channel XML configuration store backend is a simple
+       file-based backend that stores the properties and values for
+       each channel in its own file.  The file is hierarchical and may
+       look something like this:
+
+       <informalexample>
+         <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<channel name="HappyApp" version="1.0">
+    <property name="main" type="empty">
+        <property name="allow-editing" type="bool" value="true"/>
+        <property name="last-document" type="string" value="foo.txt"/>
+    </property>
+    <property name="history" type="array">
+        <value type="string" value="foo.txt"/>
+        <value type="string" value="bar.txt"/>
+        <value type="string" value="baz.txt"/>
+    </property>
+    <property name="random-stuff" type="array">
+        <value type="int" value="345"/>
+        <value type="double" value="42.4"/>
+        <value type="string" value="cheese"/>
+    </property>
+</channel>]]></programlisting>
+       </informalexample>
+     </para>
+
+     <sect2 id="xbpx-file-locations">
+       <title>File Locations</title>
+
+       <para>
+         Per-channel XML files can be located in any of the <envar>$XDG_CONFIG_DIRS</envar>,
+         under the subdirectory "xfce4/xfconf/xfce-perchannel-xml/".  The
+         user's own settings are saved in <envar>$XDG_CONFIG_HOME</envar>, under the same
+         subdirectory.
+       </para>
+    </sect2>
+
+    <sect2 id="xbpx-elements">
+      <title>Elements</title>
+
+      <itemizedlist>
+        <listitem>
+          <emphasis>&lt;channel&gt;</emphasis>: Only one &lt;channel&gt; element per file; must
+          be the top-level element.  Attributes:
+          <itemizedlist>
+            <listitem>
+              <emphasis>name</emphasis>(string): The name of the channel (required).
+            </listitem>
+            <listitem>
+              <emphasis>version</emphasis>(string): The current file version.  Right now that's
+              "1.0".  In general, files with the same 'major version' are
+              compatible with each other (required).
+            </listitem>
+            <listitem>
+              <emphasis>locked</emphasis>(userlist): A list of users/groups who cannot modify
+              any properties in this channel  (only allowed in config files
+              in non-user-writable locations; mutually exclusive with the
+              "unlocked" attribute; optional, defaults to empty).
+            </listitem>
+            <listitem>
+              <emphasis>unlocked</emphasis>(userlist): A list of users/groups who can modify
+              properties in this channel (only allowed in config files
+              in non-user-writable locations; mutually exclusive with the
+              "locked" attribute; optional, defaults to "*").
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <emphasis>&lt;property&gt;</emphasis>: Allowed as a child of the &lt;channel&gt; element
+          or another &lt;property&gt; element.  Attributes:
+          <itemizedlist>
+            <listitem>
+              <emphasis>name</emphasis>(string): The name of the property (required).
+            </listitem>
+            <listitem>
+              <emphasis>type</emphasis>(string): The type of property.  Must be one of: "string",
+              "uchar", "char", "uint16", "int16", "uint", "int", "uint64",
+              "int64", "float", "double", "bool", "array", or "empty" (required).
+              Note that due to a limitation in dbus-glib, uint16 and int16 aren't
+              actually used, but they are supported in the backend in case
+              support for 16-bit values becomes supported in the future.
+            </listitem>
+            <listitem>
+              <emphasis>value</emphasis>(string): The value of the property (required except for
+              type="array" and type="empty").
+            </listitem>
+            <listitem>
+              <emphasis>locked</emphasis>(userlist): A list of users/groups who cannot modify
+              this property (only allowed in config files in non-user-writable
+              locations; mutually exclusive with the "unlocked" attribute;
+              optional, defaults to empty).
+            </listitem>
+            <listitem>
+              <emphasis>unlocked</emphasis>(userlist): A list of users/groups who can modify
+              this property (only allowed in config files in non-user-writable
+              locations; mutually exclusive with the "locked" attribute;
+              optional, defaults to "*").
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <emphasis>&lt;value&gt;</emphasis>: Only allowed inside &lt;property&gt; elements where
+          type="array", and indicates an array element value.  Attributes:
+          <itemizedlist>
+            <listitem>
+              <emphasis>type</emphasis>(string): The type of value.  All values for type= on
+              &lt;property&gt; are supported except for "array" and "empty" (required).
+            </listitem>
+            <listitem>
+              <emphasis>value</emphasis>(string): The element's value, encoded as a string (required).
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2 id="xbpx-nesting">
+      <title>Nesting</title>
+
+      <para>
+        &lt;property&gt; elements can be nested inside other &lt;property&gt;
+        elements to create a hierarchical tree of properties.  If you were
+        to write the properties out without a tree (using the above example),
+        including the channel name, you'd have:
+
+        <informalexample>
+          <programlisting>/HappyApp/main/allow-editing
+/HappyApp/main/last-document
+/HappyApp/history</programlisting>
+        </informalexample>
+      </para>
+
+      <note>
+        These strings, minus the channel name part at the beginning, are what
+        you'd look up if using libxfconf to retrieve property values.
+      </note>
+    </sect2>
+
+    <sect2 id="xbpx-locking">
+      <title>Locking/Kiosk Mode</title>
+
+      <para>
+        System administrators can lock certain values or entire channels to
+        prevent users from changing them.  In this case, the administrator
+        may provide default values that will be used regardless of what may
+        appear in a user-writable configuration file.  If the sysadmin does
+        not wish to provide values, but only wants to lock a channel/property,
+        the application's default fallback value will be used instead.
+      </para>
+
+      <para>
+        Locking a channel or property is as simple as creating a configuration
+        file and setting either (and only either) the "locked" or "unlocked"
+        attribute on &lt;channel&gt; or &lt;property&gt; elements that should be
+        restritcted.  This configuration file should be placed in a system
+        location that is read by the daemon (see "File Locations" above).
+      </para>
+
+      <para>
+        Both the "locked" and "unlocked" attributes take a semicolon-separated
+        list of system user and group names.  User names should be entered
+        as-is, and group names should be entered with an "@" symbol prepended
+        to the group name.
+      </para>
+
+      <para>
+        The "locked" attribute specifies users and groups who may not modify
+        the property.  The "unlocked" attribute specifies users and groups
+        who may modify the property, with other users locked out.  Only
+        one of the two attributes may be specified for a particular channel
+        or property.  If both are present, the "unlocked" attribute is used,
+        and the "locked" attribute is ignored.
+      </para>
+
+      <para>
+        Note that &lt;lchannel&gt; locking locks all properties under that channel,
+        but &lt;property&gt; locking locks only the property with the "locked" or
+        "unlocked" attribute; none of the sub-properties are locked unless
+        they also contain a "locked" or "unlocked" attribute.
+      </para>
+    </sect2>
+  </sect1>
+
+</article>
diff --git a/docs/reference/xfconf-docs.sgml b/docs/reference/xfconf-docs.sgml
index 24be72f..433a38c 100644
--- a/docs/reference/xfconf-docs.sgml
+++ b/docs/reference/xfconf-docs.sgml
@@ -1,12 +1,23 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY xfconf-General SYSTEM "xfconf-general.xml">
+
+]>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>Xfconf Reference Manual</title>
   </bookinfo>
 
   <chapter>
+    <title>Xfconf Usage</title>
+    &xfconf-General;
+    <xi:include href="xfconf-general.xml"/>
+    <xi:include href="xfconf-lockdown.xml"/>
+    <xi:include href="xfconf-backends.xml"/>
+  </chapter>
+
+  <chapter>
     <title>Xfconf Core Functionality</title>
     <xi:include href="xml/xfconf-types.xml"/>
     <xi:include href="xml/xfconf-errors.xml"/>
diff --git a/docs/reference/xfconf-general.xml b/docs/reference/xfconf-general.xml
new file mode 100644
index 0000000..d2710e9
--- /dev/null
+++ b/docs/reference/xfconf-general.xml
@@ -0,0 +1,42 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<article id="xfconf-general" lang="en">
+  <sect1 id="xfconf-general-s">
+    <title>General</title>
+
+    <para>
+      Xfconf is a hierarchical (tree-like) configuration system where the
+      immediate child nodes of the root are called "channels".  All settings
+      beneath the channel nodes are called "properties."
+    </para>
+
+    <para>
+      Valid channel and property names are composed of the ASCII US-English
+      uppercase characters A-Z, lowercase characters a-z, numerals 0-9, the
+      dash (-), and underscore (_).  No other characters are allowed for
+      channel names.  The less than (&lt;) and greater than (&gt;) characters
+      (aka "angle brackets") are also allowed in property names, but not
+      in channel names.
+    </para>
+
+    <para>
+      Property names are referenced by their "full path" underneath their
+      channel, for example: "/main/history-window/last-accessed".  Of course,
+      when querying a particular property, the channel must be specified
+      separately as well.
+    </para>
+
+    <para>
+      Both channel and property names are case-insensitive.  For example,
+      the following four all refer to the same property:
+
+      <programlisting>
+        Channel: ExampleApp, property: /main/history-window/last-accessed
+        Channel: EXAMPLEAPP, property: /main/history-window/last-accessed
+        Channel: ExampleApp, property: /Main/History-Window/Last-Accessed
+        Channel: exampleapp, property: /MAIN/history-window/last-accessed
+      </programlisting>
+    </para>
+  </sect1>
+</article>
diff --git a/docs/reference/xfconf-lockdown.xml b/docs/reference/xfconf-lockdown.xml
new file mode 100644
index 0000000..3fdb42e
--- /dev/null
+++ b/docs/reference/xfconf-lockdown.xml
@@ -0,0 +1,28 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<article id="xfconf-lockdown" lang="en">
+  <sect1 id="xfconf-lockdown-s">
+    <title>Property Lockdown (Kiosk Mode)</title>
+
+    <para>
+      The Xfconf daemon supports a so-called "kiosk mode" or "lockdown mode"
+      such that certain configuration properties or certain channels can be
+      locked from user modification.  In this case, the locked values are
+      provided by a system administrator in the form of a settings file (in
+      the same format as the user's settings files) in a system read-only
+      location.
+    </para>
+
+    <para>
+      Not all backends may support kiosk/lockdown mode.  Please see the
+      documentation corresponding to your configuration backend for
+      information on how to lock down user configuration values.
+    </para>
+
+    <para>
+      (If you're unsure which backend, you're probably using the
+      "Per-channel XML" backend.)
+    </para>
+  </sect1>
+</article>