GNOME.org
 

[dconf] Add man pages

commit 8d600672d9d2b1be6de69f02ecaa98587633d2bb
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jul 25 10:43:44 2012 +0200

    Add man pages
    
    It is a nice thing if one can learn something about the running
    processes by looking up their man pages. This commit adds man pages
    for dconf-service, dconf-editor and the dconf utility in section 1.
    It also adds an overview man page in section 7. The contents of
    the overview are mostly taken from the current README. All these
    man pages are also included in the API docs, in a 'Programs'
    section.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=680602

 configure.ac            |    1 +
 docs/Makefile.am        |   29 ++++++++
 docs/dconf-docs.xml     |    9 +++
 docs/dconf-editor.xml   |   61 ++++++++++++++++
 docs/dconf-overview.xml |   99 +++++++++++++++++++++++++++
 docs/dconf-service.xml  |   63 +++++++++++++++++
 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>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]