summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/Makefile.am29
-rw-r--r--docs/dconf-docs.xml9
-rw-r--r--docs/dconf-editor.xml61
-rw-r--r--docs/dconf-overview.xml99
-rw-r--r--docs/dconf-service.xml63
-rw-r--r--docs/dconf-tool.xml174
6 files changed, 435 insertions, 0 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am
index da66f27..cbd788a 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -14,3 +14,32 @@ MKDB_OPTIONS = --output-format=xml
INCLUDES = $(gio_CFLAGS)
GTKDOC_LIBS = $(gio_LIBS) -L../client -ldconf -Wl,-rpath=../client
+
+XSLTPROC_MAN_FLAGS = \
+ --nonet \
+ --stringparam man.output.quietly 1 \
+ --stringparam funcsynopsis.style ansi \
+ --stringparam man.th.extra1.suppress 1 \
+ --stringparam man.authors.section.enabled 0 \
+ --stringparam man.copyright.section.enabled 0
+
+%.1: %.xml
+ $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_MAN_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+dconf.1: dconf-tool.xml
+ $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_MAN_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+dconf.7: dconf-overview.xml
+ $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_MAN_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+man_MANS = \
+ dconf-service.1 \
+ dconf-editor.1 \
+ dconf.1 \
+ dconf.7
+
+xml_files = ${patsubst %.1,%.xml,${patsubst %.7,%.xml,$(man_MANS)}}
+
+EXTRA_DIST += $(xml_files)
+
+DISTCLEANFILES = $(man_MANS)
diff --git a/docs/dconf-docs.xml b/docs/dconf-docs.xml
index 0def819..58ed7ec 100644
--- a/docs/dconf-docs.xml
+++ b/docs/dconf-docs.xml
@@ -9,6 +9,8 @@
</releaseinfo>
</bookinfo>
+ <xi:include href="dconf-overview.xml"/>
+
<chapter>
<title>DConf Client API</title>
<xi:include href='xml/paths.xml'/>
@@ -22,6 +24,13 @@
<xi:include href='xml/object_index.sgml'/>
</chapter>
+ <chapter id='programs'>
+ <title>Programs</title>
+ <xi:include href='dconf-service.xml'/>
+ <xi:include href='dconf-editor.xml'/>
+ <xi:include href='dconf-tool.xml'/>
+ </chapter>
+
<index id='api-index-full'>
<title>API Index</title>
<xi:include href='xml/api-index-full.xml'><xi:fallback /></xi:include>
diff --git a/docs/dconf-editor.xml b/docs/dconf-editor.xml
new file mode 100644
index 0000000..89b8942
--- /dev/null
+++ b/docs/dconf-editor.xml
@@ -0,0 +1,61 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dconf-editor">
+
+ <refentryinfo>
+ <title>dconf-editor</title>
+ <productname>dconf</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Robert</firstname>
+ <surname>Ancell</surname>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>dconf-editor</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>dconf-editor</refname>
+ <refpurpose>Graphical editor for dconf</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dconf-editor</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ The <command>dconf-editor</command> program provides a graphical interface for editing settings that are
+ stored in the dconf database. The
+ <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility
+ provides similar functionality on the commandline.
+ </para>
+
+ <para>
+ dconf-editor reads gsettings schemas from <filename>$XDG_DATA_DIRS/glib-2.0/schemas</filename> to obtain
+ descriptions, default values and allowed values for keys.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/docs/dconf-overview.xml b/docs/dconf-overview.xml
new file mode 100644
index 0000000..3700bb4
--- /dev/null
+++ b/docs/dconf-overview.xml
@@ -0,0 +1,99 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dconf-overview">
+
+ <refentryinfo>
+ <title>dconf Overview</title>
+ <productname>dconf</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Ryan</firstname>
+ <surname>Lortie</surname>
+ <email>desrt@desrt.ca</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>dconf</refentrytitle>
+ <manvolnum>7</manvolnum>
+ <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>dconf</refname>
+ <refpurpose>A configuration systen</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ dconf is a simple key/value storage system that is heavily optimised for reading. This makes it an ideal
+ system for storing user preferences (which are read 1000s of times for each time the user changes one).
+ It was created with this usecase in mind.
+ </para>
+ <para>
+ All preferences are stored in a single large binary file. Layering of preferences is possible using
+ multiple files (ie: for site defaults). Lock-down is also supported. The binary file for the defaults
+ can optionally be compiled from a set of plain text keyfiles.
+ </para>
+ <para>
+ dconf has a partial client/server architecture. It uses D-Bus. The server is only involved in writes
+ (and is not activated in the user session until the user modifies a preference). The service is stateless
+ and can exit freely at any time (and is therefore robust against crashes). The list of paths that each
+ process is watching is stored within the D-Bus daemon itself (as D-Bus signal match rules).
+ </para>
+ <para>
+ Reads are performed by direct access (via mmap) to the on-disk database which is essentially a hashtable.
+ For this reason, dconf reads typically involve zero system calls and are comparable to a hashtable lookup
+ in terms of speed. Practically speaking, in simple non-layered setups, dconf is less than 10 times slower
+ than GHashTable.
+ </para>
+ <para>
+ Writes are assumed only to happen in response to explicit user interaction (like clicking on a checkbox in
+ a preferences dialog) and are therefore not optimised at all. On some file systems, dconf-service will
+ call fsync() for every write, which can introduce a latency of up to 100ms. This latency is hidden by the
+ client libraries through a clever "fast" mechanism that records the outstanding changes locally (so they
+ can be read back immediately) until the service signals that a write has completed.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Portability</title>
+
+ <para>
+ dconf mostly targets Free Software operating systems. It will theoretically run on Mac OS but there isn't
+ much point to that (since Mac OS applications want to store preferences in plist files). It is not
+ possible to use dconf on Windows because of the inability to rename over a file that's still in use (which
+ is what the dconf-service does on every write).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>API stability</title>
+
+ <para>
+ The dconf API is not particularly friendly, and is not guaranteed to be stable. Because of this and the
+ lack of portability, you almost certainly want to use some sort of wrapper API around it. The wrapper API
+ used by GTK+ and GNOME applications is
+ <ulink url="http://developer.gnome.org/gio/stable/GSettings.html">GSettings</ulink>, which is included as
+ part of GLib. GSettings has backends for Windows (using the registry) and Mac OS (using property lists) as
+ well as its dconf backend and is the proper API to use for graphical applications.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>dconf-service</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>dconf-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <ulink url="http://developer.gnome.org/gio/stable/GSettings.html">GSettings</ulink>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/dconf-service.xml b/docs/dconf-service.xml
new file mode 100644
index 0000000..507c14d
--- /dev/null
+++ b/docs/dconf-service.xml
@@ -0,0 +1,63 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dconf-service">
+ <refentryinfo>
+ <title>dconf-service</title>
+ <productname>dconf</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Ryan</firstname>
+ <surname>Lortie</surname>
+ <email>desrt@desrt.ca</email>
+ </author>
+ </authorgroup>
+
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>dconf-service</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>dconf-service</refname>
+ <refpurpose>D-Bus service for writes to the dconf database</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dconf-service</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ The <command>dconf-service</command> program provides the <emphasis>ca.desrt.dconf</emphasis> name on the
+ session or system bus. Users or administrators should never need to start the service, as it will be
+ automatically started by
+ <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ whenever an application tries to write settings.
+ </para>
+
+ <para>
+ Reading values from the dconf database does not involve the service; it is only needed for writes. The
+ service is stateless and can exit freely at any time (and is therefore robust against crashes).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/docs/dconf-tool.xml b/docs/dconf-tool.xml
new file mode 100644
index 0000000..ae938a5
--- /dev/null
+++ b/docs/dconf-tool.xml
@@ -0,0 +1,174 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="dconf-tool">
+ <refentryinfo>
+ <title>dconf</title>
+ <productname>dconf</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Ryan</firstname>
+ <surname>Lortie</surname>
+ <email>desrt@desrt.ca</email>
+ </author>
+ </authorgroup>
+
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>dconf</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>dconf</refname>
+ <refpurpose>Simple tool for manipulating a dconf database</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">read</arg>
+ <arg choice="plain"><replaceable>KEY</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">list</arg>
+ <arg choice="plain"><replaceable>DIR</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">write</arg>
+ <arg choice="plain"><replaceable>KEY</replaceable></arg>
+ <arg choice="plain"><replaceable>VALUE</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">reset</arg>
+ <arg choice="opt">-f</arg>
+ <arg choice="plain"><replaceable>PATH</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">update</arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">watch</arg>
+ <arg choice="plain"><replaceable>PATH</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">dump</arg>
+ <arg choice="plain"><replaceable>DIR</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">load</arg>
+ <arg choice="plain"><replaceable>DIR</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>dconf</command>
+ <arg choice="plain">help</arg>
+ <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ The <command>dconf</command> program can perform various operations on a dconf database, such as reading
+ or writing individual values or entire directories. This tool operates directly on the dconf database and
+ does not read gsettings schema information. Therefore, it cannot perform type and consistency checks on
+ values. The <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ utility is an alternative if such checks are needed.
+ </para>
+
+ <para>
+ The <replaceable>DIR</replaceable> arguments must be directory paths (starting and ending with '/'), the
+ <replaceable>KEY</replaceable> arguments must be key paths (starting, but not ending with '/') and the
+ <replaceable>PATH</replaceable> arguments can be either directory or key paths.
+ </para>
+
+ <para>
+ <replaceable>VALUE</replaceable> arguments must be in GVariant format, so e.g. a string must include
+ explicit quotes: "'foo'". This format is also used when printing out values.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Commands</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>read</option></term>
+
+ <listitem><para>Read the value of a key.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>list</option></term>
+
+ <listitem><para>List the sub-keys and sub-directories of a directory.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>write</option></term>
+
+ <listitem><para>Write a new value to a key.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>reset</option></term>
+
+ <listitem><para>Reset a key or an entire directory. For directories, <option>-f</option> must be specified.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>update</option></term>
+
+ <listitem><para>Update the system dconf databases.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>watch</option></term>
+
+ <listitem><para>Watch a key or directory for changes.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>dump</option></term>
+
+ <listitem><para>Dump an entire subpath to stdout. The output is in a keyfile-like format, with values in GVariant syntax.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>load</option></term>
+
+ <listitem><para>Populate a subpath from stdin. The expected format is the same as produced by <option>dump</option>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>help</option></term>
+
+ <listitem><para>Display help and exit. If <replaceable>COMMAND</replaceable> is given, display help for this command.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>dconf-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>