[Xfce4-commits] <xfconf:docs-consolidation> WIP
Brian J. Tarricone
noreply at xfce.org
Fri Jan 29 07:14:04 CET 2010
Updating branch refs/heads/docs-consolidation
to 7d3781bb1a674583515d4cc08e76175972e1f56c (commit)
from f7effe6907669d8ed9d1ee4fa2c09bc451df66cd (commit)
commit 7d3781bb1a674583515d4cc08e76175972e1f56c
Author: Brian J. Tarricone <brian at tarricone.org>
Date: Thu Aug 13 00:40:12 2009 -0700
WIP
docs/reference/tmpl/xfconf-channel.sgml | 5 +
docs/reference/xfconf-backends.xml | 251 +++++++++++++++++++++++++++++++
docs/reference/xfconf-docs.sgml | 13 ++-
docs/reference/xfconf-general.xml | 42 +++++
docs/reference/xfconf-lockdown.xml | 28 ++++
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><channel></emphasis>: Only one <channel> 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><property></emphasis>: Allowed as a child of the <channel> element
+ or another <property> 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><value></emphasis>: Only allowed inside <property> 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
+ <property> 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>
+ <property> elements can be nested inside other <property>
+ 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 <channel> or <property> 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 <lchannel> locking locks all properties under that channel,
+ but <property> 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 (<) and greater than (>) 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>
More information about the Xfce4-commits
mailing list