add some preliminary specs/behavior descriptions

(Old svn revision: 26733)

5 files changed, 133 insertions, 2 deletions

diff --git a/docs/spec/Makefile.am b/docs/spec/Makefile.am
index 7ba7b2d..eae79c8 100644
--- a/docs/spec/Makefile.am
+++ b/docs/spec/Makefile.am
@@ -1,2 +1,5 @@
 EXTRA_DIST = \
-	perchannel-xml.did
+	general.txt \
+	lockdown-behavior.txt \
+	perchannel-xml.dtd \
+	perchannel-xml-txt
diff --git a/docs/spec/general.txt b/docs/spec/general.txt
new file mode 100644
index 0000000..283662e
--- /dev/null
+++ b/docs/spec/general.txt
@@ -0,0 +1,20 @@
+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."
+
+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.
+
+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.
+
+Both channel and property names are case-insensitive.  For example,
+the following four all refer to the same property:
+
+  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
diff --git a/docs/spec/lockdown-behavior.txt b/docs/spec/lockdown-behavior.txt
new file mode 100644
index 0000000..daa1bc6
--- /dev/null
+++ b/docs/spec/lockdown-behavior.txt
@@ -0,0 +1,13 @@
+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.
+
+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.
+
+(If you're unsure which backend, you're probably using the
+"Per-channel XML" backend.)
diff --git a/docs/spec/perchannel-xml.dtd b/docs/spec/perchannel-xml.dtd
index 118becf..c80767d 100644
--- a/docs/spec/perchannel-xml.dtd
+++ b/docs/spec/perchannel-xml.dtd
@@ -5,11 +5,13 @@
 <!ELEMENT string #PCDATA>
 
 <!ATTLIST channel name CDATA #REQUIRED>
-<!ATTLIST channel version CDATA #REQUIRED>
+<!ATTLIST channel version CDATA #REQUIRED>  <!-- currently "1.0" -->
+<!ATTLIST channel locked (true|false) #IMPLIED>
 
 <!ATTLIST property name CDATA #REQUIRED>
 <!ATTLIST property type (string|strlist|int|int64|double|bool|empty) #REQUIRED>
 <!ATTLIST property value CDATA #IMPLIED>  <!-- not used if type="strlist"
                                                or type="empty" -->
+<!ATTLIST property locked (true|false) #IMPLIED>
 
 <!-- <string> element has no attributes -->
diff --git a/docs/spec/perchannel-xml.txt b/docs/spec/perchannel-xml.txt
new file mode 100644
index 0000000..b26241c
--- /dev/null
+++ b/docs/spec/perchannel-xml.txt
@@ -0,0 +1,93 @@
+-> High-level overview:
+
+   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:
+   
+   <?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="strlist">
+           <string>foo.txt</string>
+           <string>bar.txt</string>
+           <string>baz.txt</string>
+       </property>
+   </channel>
+
+
+-> File locations:
+
+   Per-channel XML files can be located in any of the $XDG_CONFIG_DIRS,
+   under the subdirectory "xfce4/xfconf/xfce-perchannel-xml/".  The
+   user's own settings are saved in $XDG_CONFIG_HOME, under the same
+   subdirectory.
+
+
+-> Elements:
+
+   * <channel>
+     Only one <channel> element per file; must be the top-level element.
+     Attributes:
+       + name(string): The name of the channel (required).
+       + version(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).
+       + locked(bool): Whether or not the channel is locked to prevent
+         user modification (only allowed in config files in
+         non-user-writable locations; optional, defaults to "false").
+   * <property>
+     Allowed as a child of the <channel> element or another <property>
+     element.
+     Attributes:
+       + name(string): The name of the property (required).
+       + type(string): The type of property.  Must be one of: "string",
+         "strlist", "int", "int64", "double", "bool", "empty" (required).
+       + value(string): The value of the property (required except for
+         type="strlist" and type="empty").
+       + locked(bool): Whether or not the property is locked to prevent
+         user modification (only allowed in config files in
+         non-user-writable locations; optional, defaults to "false").
+   * <string>
+     Only allowed inside <property> elements where type="strlist".  Has
+     no attributes; the text between the opening and closing tags is
+     the property value.
+
+
+-> Nesting:
+
+   <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:
+   
+   /HappyApp/main/allow-editing
+   /HappyApp/main/last-document
+   /HappyApp/history
+   
+   (These strings are what you'd look up if using libxfconf to retrieve
+   property values.)
+
+
+-> Locking/Kiosk mode:
+
+   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.
+   
+   Locking a channel or property is as simple as creating a configuration
+   file and setting the "locked" attribute to "true" on <channel> or
+   <property> elements that should be locked.  This configuration file
+   should be placed in a system location that is read by the daemon
+   (see "File locations" above).
+   
+   Note that <channel> locking locks all properties under that channel,
+   but <property> locking locks only the property with the locked="true"
+   attribute; none of the sub-properties are locked unless they also
+   contain the locked="true" attribute.