diff options
| -rw-r--r-- | configure.ac | 1 | ||||
| -rw-r--r-- | docs/Makefile.am | 29 | ||||
| -rw-r--r-- | docs/dconf-docs.xml | 9 | ||||
| -rw-r--r-- | docs/dconf-editor.xml | 61 | ||||
| -rw-r--r-- | docs/dconf-overview.xml | 99 | ||||
| -rw-r--r-- | docs/dconf-service.xml | 63 | ||||
| -rw-r--r-- | docs/dconf-tool.xml | 174 |
7 files changed, 436 insertions, 0 deletions
diff --git a/configure.ac b/configure.ac index f82571c..0999e40 100644 --- a/configure.ac +++ b/configure.ac @@ -20,6 +20,7 @@ fi AC_PROG_CC AM_PROG_VALAC([0.17.0]) AC_PROG_RANLIB +AC_PATH_PROG([XSLTPROC], [xsltproc]) # Use GSettings GLIB_GSETTINGS 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> |