Updating branch refs/heads/docs-consolidation to 7d3781bb1a674583515d4cc08e76175972e1f56c (commit) from f7effe6907669d8ed9d1ee4fa2c09bc451df66cd (commit)
commit 7d3781bb1a674583515d4cc08e76175972e1f56c Author: Brian J. Tarricone <br...@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> _______________________________________________ Xfce4-commits mailing list Xfce4-commits@xfce.org http://foo-projects.org/mailman/listinfo/xfce4-commits