doc: Move manual into doc/manual subdirectory

14 files changed, 1532 insertions, 0 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
new file mode 100644
index 0000000..59c8624
--- /dev/null
+++ b/doc/manual/Makefile.am
@@ -0,0 +1,132 @@
+abs_top_builddir = @abs_top_builddir@
+
+NULL =
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=p11-kit
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../../p11-kit
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS= --version
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS= --rebuild-types --deprecated-guards="P11_KIT_DISABLE_DEPRECATED"
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/p11-kit/*.h
+CFILE_GLOB=$(top_srcdir)/p11-kit/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES= \
+	private.h \
+	pkcs11.h \
+	conf.h \
+	debug.h \
+	dict.h \
+	mock-module.h \
+	pkcs11.h \
+	pkcs11x.h \
+	private.h \
+	util.h \
+	array.h \
+	compat.h \
+	mock-module.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=p11-kit-config.xml p11-kit-sharing.xml \
+	p11-kit-devel.xml \
+	p11-kit-trust.xml \
+	p11-kit.xml \
+	annotation-glossary.xml \
+	$(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+INCLUDES=
+GTKDOC_LIBS=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+if ENABLE_GTK_DOC
+man8_MANS = p11-kit.8
+man5_MANS = pkcs11.conf.5
+
+XSLTPROC_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
+
+XSLTPROC_MAN = \
+	$(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+
+.xml.5:
+	$(AM_V_GEN) $(XSLTPROC_MAN) $<
+.xml.8:
+	$(AM_V_GEN) $(XSLTPROC_MAN) $<
+
+else # ENABLE_GTK_DOC
+
+man5_MANS =
+man8_MANS =
+
+endif # ENABLE_GTK_DOC
+
+MAN_IN_FILES = \
+	$(man8_MANS:.8=.xml) \
+	$(man5_MANS:.5=.xml) \
+	$(NULL)
+
+CLEANFILES += \
+	$(man5_MANS) \
+	$(man8_MANS) \
+	$(NULL)
+
+EXTRA_DIST += \
+	$(MAN_IN_FILES) \
+	version.xml.in \
+	version.xml \
+	$(NULL)
diff --git a/doc/manual/annotation-glossary.xml b/doc/manual/annotation-glossary.xml
new file mode 100644
index 0000000..4a0f8a6
--- /dev/null
+++ b/doc/manual/annotation-glossary.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+
+<glossary id="annotation-glossary">
+<title>Annotation Glossary</title>
+<glossdiv><title>A</title>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-allow-none"/>allow-none</glossterm>
+		<glossdef>
+			<para>NULL is ok, both for passing and for returning.</para>
+		</glossdef>
+	</glossentry>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-array"/>array</glossterm>
+		<glossdef>
+			<para>Parameter points to an array of items.</para>
+		</glossdef>
+	</glossentry>
+</glossdiv>
+<glossdiv><title>E</title>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-element-type"/>element-type</glossterm>
+		<glossdef>
+			<para>Generics and defining elements of containers and arrays.</para>
+		</glossdef>
+	</glossentry>
+</glossdiv>
+<glossdiv><title>I</title>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-inout"/>inout</glossterm>
+		<glossdef>
+			<para>Parameter for input and for returning results. Default is <acronym>transfer full</acronym>.</para>
+		</glossdef>
+	</glossentry>
+</glossdiv>
+<glossdiv><title>O</title>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-out"/>out</glossterm>
+		<glossdef>
+			<para>Parameter for returning results. Default is <acronym>transfer full</acronym>.</para>
+		</glossdef>
+	</glossentry>
+</glossdiv>
+<glossdiv><title>T</title>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-transfer full"/>transfer full</glossterm>
+		<glossdef>
+			<para>Free data after the code is done.</para>
+		</glossdef>
+	</glossentry>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-type"/>type</glossterm>
+		<glossdef>
+			<para>Override the parsed C type with given type</para>
+		</glossdef>
+	</glossentry>
+	<glossentry>
+		<glossterm><anchor id="annotation-glossterm-transfer none"/>transfer none</glossterm>
+		<glossdef>
+			<para>Don't free data after the code is done.</para>
+		</glossdef>
+	</glossentry>
+</glossdiv>
+</glossary>
\ No newline at end of file
diff --git a/doc/manual/docbook-params.xsl b/doc/manual/docbook-params.xsl
new file mode 100644
index 0000000..5d8591a
--- /dev/null
+++ b/doc/manual/docbook-params.xsl
@@ -0,0 +1,39 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!--
+    Parameters for DocBook transformation.
+
+    Copyright (C) 2009 Michael Leupold <lemma@confuego.org>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+-->
+
+    <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+
+    <xsl:param name="toc.max.depth">3</xsl:param>
+    <xsl:param name="generate.section.toc.level">0</xsl:param>
+    <xsl:param name="generate.toc">
+        book     toc
+        part     nop
+        chapter  toc
+    </xsl:param>
+    <xsl:param name="html.stylesheet">style.css</xsl:param>
+    <xsl:param name="funcsynopsis.style">ansi</xsl:param>
+    <xsl:param name="funcsynopsis.decoration">1</xsl:param>
+    <xsl:param name="refentry.generate.name">0</xsl:param>
+    <xsl:param name="refentry.generate.title">1</xsl:param>
+
+</xsl:stylesheet>
diff --git a/doc/manual/p11-kit-config.xml b/doc/manual/p11-kit-config.xml
new file mode 100644
index 0000000..ca07769
--- /dev/null
+++ b/doc/manual/p11-kit-config.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="config">
+	<title>PKCS#11 Configuration</title>
+
+	<section id="config-introduction">
+		<title>Consistent configuration</title>
+
+		<para>In order for multiple applications on the user's desktop to use
+			PKCS#11 modules in a consistent manner, there must be a configuration
+			or registry to specify which modules to load and how to use them. The
+			PKCS#11 specification does not specify such a configuration standard.
+		</para>
+
+		<para>Because of the multi-library module initialization problem, use of
+			PKCS#11 modules must be coordinated within an application. p11-kit
+			provides that coordination. Since coordination is required, it follows
+			that p11-kit can also implement a consistent module configuration.
+		</para>
+	</section>
+
+	<section id="config-example">
+		<title>Example</title>
+
+		<para>The following sections describe the config format in detail. But first
+		an example which shows the various features. The configuration below, loads
+		two modules called 'my-module' and 'nss'. The user settings override some
+		aspects of the system settings.</para>
+
+<para>Global configuration file: <literal>/etc/pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This setting controls whether to load user configuration from the
+# ~/.pkcs11 directory. Possible values:
+#    none: No user configuration
+#    merge: Merge the user config over the system configuration (default)
+#    only: Only user configuration, ignore system configuration
+user-config: merge
+</programlisting>
+
+<para>One module configuration file per module: <literal>/etc/pkcs11/modules/my-module</literal></para>
+<programlisting>
+# This setting controls the actual module library to load. This config file
+# might be installed by the package that installs this module library. This
+# is not an absolute path name. Relative path names are loaded from the
+# $(libdir)/pkcs11 directory by default.
+module: my-pkcs11-module.so
+
+# This controls whether the module is required to successfully initialize. If 'yes', then
+# a failure to load or initialize this module will result in a p11-kit system failure.
+critical: no
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/pkcs11.conf</literal></para>
+<programlisting>
+# This is an empty file. Files that do not exist are treated as empty.
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/my-module</literal></para>
+<programlisting>
+# Merge with the settings in the system my-module config file. In this case
+# a developer has overridden to load a different module for my-module instead.
+module: /home/user/src/custom-module/my-module.so
+</programlisting>
+
+<para>User configuration file: <literal>~/.pkcs11/modules/nss</literal></para>
+<programlisting>
+# Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass
+# some custom non-standard initialization arguments, as NSS expects.
+module: /usr/lib/libsoftokn3.so
+x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db'
+critical: yes
+</programlisting>
+
+
+</section>
+
+<section>
+	<title>Configuration Files</title>
+
+	<para>A complete configuration consists of several files. These files are
+	text files. Since <literal>p11-kit</literal> is built to be used in all
+	sorts of environments and at very low levels of the software stack, we
+	cannot make use of high level configuration APIs that you may find on a
+	modern desktop.</para>
+
+	<para><link linkend="pkcs11.conf">See the manual page</link> for more details
+	on the format and available options.</para>
+</section>
+</chapter>
diff --git a/doc/manual/p11-kit-devel.xml b/doc/manual/p11-kit-devel.xml
new file mode 100644
index 0000000..bbe6c0a
--- /dev/null
+++ b/doc/manual/p11-kit-devel.xml
@@ -0,0 +1,299 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="devel">
+	<title>Building, Packaging, and Contributing to p11-kit</title>
+
+	<section id="devel-links">
+		<title>Helpful Resources</title>
+
+		<para>Use the following to find more information about
+		contributing to p11-kit beyond what's in this manual:</para>
+
+		<itemizedlist>
+			<listitem><para><ulink url="http://p11-glue.freedesktop.org/p11-kit.html">Website</ulink></para></listitem>
+			<listitem><para><ulink url="mail:p11-glue@lists.freedesktop.org">Mailing list</ulink></para></listitem>
+			<listitem><para><ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit">Bugzilla</ulink></para></listitem>
+		</itemizedlist>
+	</section>
+
+	<section id="devel-paths">
+		<title>Packaging PKCS#11 module configs</title>
+
+		<para>Developers or packagers of PKCS#11 modules need to install various
+		files into specific locations so that p11-kit will recognize and load the
+		module correctly.</para>
+
+		<para>You should use <literal>pkg-config</literal> as described below
+		to determine configuration paths. p11-kit installs a
+		<literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>.
+		This file contains all the information about the various paths that p11-kit
+		looks for files at.</para>
+
+		<section id="devel-paths-config">
+			<title>Path to place module configuration</title>
+
+			<para>As described in the <link linkend="config-module">module configuration</link>
+			documentation, each PKCS#11 module should install a config file describing
+			that module. These config files should be installed to a specific directory which
+			can be determined by running:</para>
+
+			<programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_module_configs</command>
+/usr/share/p11-kit/modules</programlisting>
+		</section>
+
+		<section id="devel-paths-modules">
+			<title>Default path for modules with relative paths</title>
+
+			<para>If a <link linkend="config-module">module configuration</link>
+			contains a relative path in its <literal>module:</literal> setting,
+			then that module will be loaded from the default module path. This
+			path can be determined by running:</para>
+
+			<programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_module_path</command>
+/usr/lib64/pkcs11</programlisting>
+		</section>
+
+	</section>
+
+	<section id="devel-commands">
+		<title>Customizing installed commands</title>
+
+		<para>The <literal>p11-kit</literal> tool provides a
+		<literal>extract-trust</literal> command which extracts trust
+		policy information such as certificate anchors and so on
+		into files for use with libraries that cannot read this trust
+		information directly.</para>
+
+		<para>In order to be useful the <literal>extract-trust</literal>
+		command needs to be customized per distribution or site. You can
+		find this file in at <literal>tools/p11-kit-trust-extract.in</literal>
+		in the p11-kit source code.</para>
+
+		<para>The command is implemented as a simple script which
+		performs the various <literal>p11-kit extract</literal> commands
+		necessary to extract the information.</para>
+
+		<para>Using this script as a standard way to extract this
+		information allows for consistency between distributions and ease
+		of system administration.</para>
+	</section>
+
+	<section id="devel-building">
+		<title>Compiling p11-kit from Source</title>
+		<para>This describes how to compiling the p11-kit package from
+		source code. This is normally only necessary for those wishing to
+		contribute to the project or package p11-kit.</para>
+
+		<para>You can download
+		<ulink url="http://p11-glue.freedesktop.org/releases/">tarballs
+		of the releases</ulink> of p11-kit or
+		<ulink url="http://cgit.freedesktop.org/p11-glue/p11-kit/">check
+		out the source code from git</ulink>. This documentation will not
+		go into all the details of how to get your development environment
+		set up and instead focus on the what's unique to compiling p11-kit.</para>
+
+		<section id="devel-building-unix">
+			<title>Building on UNIX</title>
+			<para>p11-kit uses the standard GNU build system, using autoconf for package
+			configuration and resolving portability issues, automake for building makefiles
+			that comply with the GNU Coding Standards, and libtool for building shared
+			libraries on multiple platforms. The normal sequence for compiling and
+			installing the p11-kit library is thus:</para>
+
+<programlisting>
+$ ./configure --prefix=/path/to/prefix ...
+$ make
+$ make install
+</programlisting>
+
+			<para>If you've checked out the source code from git, then the
+			<command>configure</command> script does not yet exist. So use
+			the following instead:</para>
+
+<programlisting>
+$ ./autogen.sh --prefix=/path/to/prefix ...
+$ make
+$ make install
+</programlisting>
+
+			<para>The standard options provided by GNU autoconf may be passed to the configure
+			script. Please see the autoconf documentation or run <literal>./configure --help</literal>
+			for information about the standard options. In particular you probably want to adjust
+			the <literal>--prefix=/xxx</literal> argument depending on your system and development
+			environment.</para>
+		</section>
+
+		<section id="devel-building-dependencies">
+			<title>Optional Dependencies</title>
+
+			<para>On a modern GNU Linux system, p11-kit has no required dependencies other
+			than the standard C library. However on older UNIX systems, some of the following
+			may be required.</para>
+
+			<itemizedlist>
+				<listitem><para><command>gettext</command> is required if your system doesn't
+				have the <literal>gettext()</literal> functionality for handling message
+				translation databases. This can be provided by the libintl library from
+				the <ulink url="http://www.gnu.org/software/gettext">GNU gettext
+				package</ulink>.</para></listitem>
+				<listitem><para><command>pthread</command> is required if your (ancient) system
+				doesn't have this included in the base system. How this is provided is platform
+				specific.</para></listitem>
+			</itemizedlist>
+
+			<para>In addition p11-kit has several optional dependencies. If these are not available
+			during the build, then certain features will be disabled.</para>
+
+			<itemizedlist>
+				<listitem><para><command>gtk-doc</command> is required to build the reference
+				manual. Use <literal>--enable-doc</literal> to control this
+				dependency.</para></listitem>
+				<listitem><para><command>xsltproc</command> is required to build the command
+				manual pages. Use <literal>--enable-doc</literal> to control this
+				dependency.</para></listitem>
+				<listitem><para><command>libtasn1</command> is required to build the trust
+				module and code that interacts with certificates.</para></listitem>
+			</itemizedlist>
+
+		</section>
+
+		<section id="devel-building-configure">
+			<title>Extra Configuration Options</title>
+
+			<para>In addition to the normal options, the configure script in the p11-kit library
+			supports these additional arguments:</para>
+
+			<variablelist>
+				<varlistentry>
+					<term><option>--disable-trust-module</option></term>
+					<listitem><para>Disables building of the trust policy module.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--disable-debug</option>, <option>--enable-debug</option></term>
+					<listitem><para>By default p11-kit is built with debug symbols assertions and
+					and precondition checks. Enabling the debug option configures even more
+					detailed debug build, including disabling optimization. Disabling the debug
+					option is not recommended, as it disables all assertions, preconditions and
+					internal consistency checks, although it may result it a slightly faster
+					library.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--enable-doc</option></term>
+					<listitem><para>Enables building of the documentation and command line manual.
+					The documentation is built in the <literal>doc/html/</literal> directory of
+					the build. Requires the <literal>gtk-doc</literal> and <literal>xsltproc</literal>
+					dependencies.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--enable-strict</option></term>
+					<listitem><para>Enables strict checks during building of p11-kit. All
+					compiler warnings become errors.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--with-libtasn1</option>, <option>--without-libtasn1</option></term>
+					<listitem><para>Build with a dependency on the libtasn1 library. This dependency
+					allows the trust policy module to be built as well as other code that interacts with
+					certificates.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--with-module-path</option></term>
+					<listitem><para>Specify the path to look for PKCS#11 modules which were
+					listed in a module config file with a relative path.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--with-system-anchors</option></term>
+					<listitem><para>Specify the files or directories to look for system
+					certificate anchors. Multiple files and/or directories are specified with
+					a <literal>:</literal> in between them.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--with-system-certificates</option></term>
+					<listitem><para>Specify the files or directories to look for other
+					non-anchor system certificates. Multiple files and/or directories are
+					specified with a <literal>:</literal> in between them.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>--with-system-config</option></term>
+					<listitem><para>Specify the path to look for p11-kit config files. This
+					usually defaults to something like <literal>/etc/pkcs11</literal></para></listitem>
+				</varlistentry>
+			</variablelist>
+			<para></para>
+		</section>
+	</section>
+
+	<section id="devel-building-style">
+		<title>Coding Style</title>
+
+		<para>We use a code style similar to the linux kernel. Use tabs
+		to indent and spaces to align/wrap beyond the indentation level.</para>
+
+		<para>We don't try to guarantee completely robust and problem free
+		behavior in cases where the caller or system isn't behaving. We
+		consider these to be outside of our control:</para>
+
+		<itemizedlist>
+			<listitem><para>Broken input from callers. We use preconditions
+			to check input and immediately return. We don't try to provide
+			error codes for all the various ways callers can screw
+			around.</para></listitem>
+
+			<listitem>
+			<para>Out of memory. It is pretty much impossible to handle out
+			of memory errors correctly. Handling them alongside other errors
+			is naive and broken. We don't try to guarantee library state
+			(such as locks or memory leaks) when memory allocation fails.</para>
+			<para>We do check the results from all memory allocations, but
+			treat them as unexpected conditions. As a nod to the behavior
+			of callers of this library, we don't abort on memory allocation
+			failures. We use preconditions with somewhat sane results.</para>
+			<para>Exception: when reading files or allocating potentially
+			unbounded amounts of memory, we should respond robustly to memory
+			allocation failures.</para>
+			</listitem>
+		</itemizedlist>
+
+		<para>These unexpected conditions indicate a bug either in p11-kit or
+		in the system. All bets are off once this occurs.</para>
+
+		<para>Use the <literal>return_val_xxx()</literal> precondition macros to
+		check for unexpected conditions.</para>
+	</section>
+
+	<section id="devel-testing">
+		<title>Testing and Code Coverage</title>
+
+		<para>As a general rule changes to p11-kit should have a tests exercising
+		that change. Use the <literal>make check</literal> command to run all
+		the tests. If you run it from a subdirectory only the tests in that
+		directory will be run.</para>
+
+		<para>Build p11-kit with the <option>--enable-coverage</option> configure
+		option to build code coverage support.</para>
+
+		<para>Once you've done that you can either use <literal>make coverage</literal>
+		to build code coverage information. Alternatively (and this is usually
+		easier) you can use
+		<ulink url="http://stef.thewalter.net/2012/12/git-coverage-useful-code-coverage.html">
+			<literal>git coverage</literal></ulink> to easily check whether
+		you've tested the lines changed by a patch.</para>
+
+		<para>A code coverage report is
+			<ulink url="http://p11-glue.freedesktop.org/build/coverage">available online</ulink></para>.
+	</section>
+
+	<section id="devel-debugging">
+		<title>Debugging Tips</title>
+
+		<para>Unexpected conditions will produce critical warnings by p11-kit.
+		These are often failed internal preconditions, and usually indicate a
+		bug either in p11-kit or the software calling it.</para>
+
+		<para>You can use the environment variable <literal>P11_KIT_STRICT=yes</literal>
+		to make p11-kit do an <literal>abort()</literal> (and core dump depending on
+		your configuration) when a critical warning occurs.</para>
+	</section>
+</chapter>
diff --git a/doc/manual/p11-kit-docs.sgml b/doc/manual/p11-kit-docs.sgml
new file mode 100644
index 0000000..0397169
--- /dev/null
+++ b/doc/manual/p11-kit-docs.sgml
@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+	<bookinfo>
+		<title>p11-kit</title>
+		<releaseinfo>for p11-kit &version;</releaseinfo>
+	</bookinfo>
+
+	<xi:include href="p11-kit-config.xml"/>
+	<xi:include href="p11-kit-sharing.xml"/>
+	<xi:include href="p11-kit-trust.xml"/>
+
+	<chapter xml:id="tools">
+		<title>Manual Pages</title>
+		<xi:include href="p11-kit.xml"/>
+		<xi:include href="pkcs11.conf.xml"/>
+	</chapter>
+
+	<chapter xml:id="reference">
+		<title>API Reference</title>
+		<xi:include href="xml/p11-kit.xml"/>
+		<xi:include href="xml/p11-kit-uri.xml"/>
+		<xi:include href="xml/p11-kit-pin.xml"/>
+		<xi:include href="xml/p11-kit-util.xml"/>
+		<xi:include href="xml/p11-kit-future.xml"/>
+
+		<index id="api-index-full">
+			<title>API Index</title>
+			<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+		</index>
+
+		<xi:include href="annotation-glossary.xml"/>
+	</chapter>
+
+	<xi:include href="p11-kit-devel.xml"/>
+
+</book>
diff --git a/doc/manual/p11-kit-overrides.txt b/doc/manual/p11-kit-overrides.txt
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/manual/p11-kit-overrides.txt
diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt
new file mode 100644
index 0000000..dc85f2d
--- /dev/null
+++ b/doc/manual/p11-kit-sections.txt
@@ -0,0 +1,106 @@
+<SECTION>
+<FILE>p11-kit-uri</FILE>
+P11_KIT_URI_SCHEME
+P11_KIT_URI_SCHEME_LEN
+P11KitUriType
+P11KitUriResult
+P11KitUri
+p11_kit_uri_new
+p11_kit_uri_get_module_info
+p11_kit_uri_match_module_info
+p11_kit_uri_get_token_info
+p11_kit_uri_match_token_info
+p11_kit_uri_get_attributes
+p11_kit_uri_set_attributes
+p11_kit_uri_clear_attributes
+p11_kit_uri_match_attributes
+p11_kit_uri_get_attribute
+p11_kit_uri_set_attribute
+p11_kit_uri_clear_attribute
+p11_kit_uri_set_unrecognized
+p11_kit_uri_any_unrecognized
+p11_kit_uri_get_pin_source
+p11_kit_uri_set_pin_source
+p11_kit_uri_get_pinfile
+p11_kit_uri_set_pinfile
+p11_kit_uri_format
+p11_kit_uri_parse
+p11_kit_uri_free
+p11_kit_uri_message
+P11_KIT_URI_NO_MEMORY
+</SECTION>
+
+<SECTION>
+<FILE>p11-kit-pin</FILE>
+P11KitPin
+p11_kit_pin_new
+p11_kit_pin_new_for_buffer
+p11_kit_pin_new_for_string
+p11_kit_pin_get_value
+p11_kit_pin_get_length
+p11_kit_pin_ref
+p11_kit_pin_unref
+P11KitPinFlags
+P11_KIT_PIN_FALLBACK
+p11_kit_pin_register_callback
+p11_kit_pin_unregister_callback
+p11_kit_pin_callback
+p11_kit_pin_request
+p11_kit_pin_destroy_func
+p11_kit_pin_file_callback
+</SECTION>
+
+<SECTION>
+<FILE>p11-kit</FILE>
+p11_kit_initialize_registered
+p11_kit_finalize_registered
+p11_kit_registered_modules
+p11_kit_registered_module_to_name
+p11_kit_registered_name_to_module
+p11_kit_registered_option
+p11_kit_initialize_module
+p11_kit_load_initialize_module
+p11_kit_finalize_module
+</SECTION>
+
+<SECTION>
+<FILE>p11-kit-util</FILE>
+p11_kit_strerror
+p11_kit_space_strdup
+p11_kit_space_strlen
+<SUBSECTION Private>
+CK_FUNCTION_LIST_PTR
+CK_RV
+CK_ATTRIBUTE_PTR
+CK_ATTRIBUTE_TYPE
+CK_INFO_PTR
+CK_TOKEN_INFO_PTR
+CK_ULONG
+p11_kit_uri_result_t
+p11_kit_uri_type_t
+</SECTION>
+
+<SECTION>
+<FILE>p11-kit-future</FILE>
+p11_kit_set_progname
+p11_kit_be_quiet
+p11_kit_be_loud
+p11_kit_message
+p11_kit_destroyer
+P11KitIter
+p11_kit_iter_new
+p11_kit_iter_set_session_flags
+p11_kit_iter_add_callback
+p11_kit_iter_callback
+p11_kit_iter_add_filter
+p11_kit_iter_begin
+p11_kit_iter_begin_with
+p11_kit_iter_next
+p11_kit_iter_get_module
+p11_kit_iter_get_slot
+p11_kit_iter_get_session
+p11_kit_iter_keep_session
+p11_kit_iter_get_object
+p11_kit_iter_load_attributes
+p11_kit_iter_free
+</SECTION>
diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml
new file mode 100644
index 0000000..a1c19a7
--- /dev/null
+++ b/doc/manual/p11-kit-sharing.xml
@@ -0,0 +1,92 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="sharing">
+	<title>Sharing PKCS#11 modules</title>
+
+	<section xml:id="sharing-problem">
+		<title>Multiple consumers of PKCS#11 in a process</title>
+
+		<para>As more and more applications and libraries use PKCS#11 we run
+		into a very basic problem. The PKCS#11 modules cannot be initialized and
+		finalized properly without coordination between the various consumers.
+		</para>
+
+		<para>An example: An application might use GnuTLS for
+		TLS connections, and use libgcr for display of certificates. Both of
+		these want to load (and initialze) the same PKCS#11 modules. There are
+		many places where this situation occurs, including large applications
+		like Evolution which due to their dependencies end up using both NSS and
+		GnuTLS.</para>
+
+		<para>Consumer A loads a PKCS#11 module and uses the module's
+		C_Initialize function to initialize it, which works as expected.
+		When consumer B initializes the module (also using C_Initialize),
+		the error code <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
+		is correctly returned. This is normal PKCS#11 specification
+		defined behavior for when a module is initalized twice in the
+		same process. If consumer B is aware of this situation they may
+		choose to ignore this error code.</para>
+
+		<para>However when the consumer A is done with its use of the
+		PKCS#11 module it finalizes the module using the module's
+		C_Finalize function. This is expected of a well behaved PKCS#11
+		consumer. This then causes errors and/or crashes for consumer B,
+		which cannot know that the module has now been finalized out
+		from underneath it.</para>
+
+		<para>It is necessary for the two consumers to coordinate their
+		initialization and finalization in some fashion. In
+		<literal>p11-kit</literal> we provide this coordination in a
+		loosely coupled, backwards compatible, and flexible way.</para>
+	</section>
+
+	<section xml:id="sharing-initialize">
+		<title>Solution: p11-kit</title>
+
+		<para><literal>p11-kit</literal> provides functions to
+		coordinate initialization and finalization of any PKCS#11
+		module. A module may be initialized any number of times using
+		the p11_kit_initialize_module() function. The first time that
+		p11_kit_initialize_module() is called for a module, that module's
+		C_Initialize function is used. Later invocations for the same
+		module cause p11-kit to increment an internal initialization
+		count, rather than calling C_Initialize again.</para>
+
+		<para>The p11_kit_finalize_module() is used to finalize a module.
+		Each time it is called it decrements the internal initialization
+		count for that module. When the internal initialization count
+		reaches zero, the module's C_Finalize function is called.</para>
+
+		<para>This is done in a thread-safe manner. These functions can
+		be used on modules that the consumer loads themselves.</para>
+	</section>
+
+	<section xml:id="sharing-module">
+		<title>Solution: proxy module</title>
+
+		<para>When an application is aware of the fact that coordination
+		is necessary between multiple consumers of a PKCS#11 module, it
+		can link to p11-kit and use the functions there to provide
+		this coordination.</para>
+
+		<para>However most current consumers of PKCS#11 are ignorant of
+		this problem, and do not link to p11-kit. In order to solve this
+		multiple initialization problem for all applications,
+		<literal>p11-kit</literal> provides a proxy compatibility
+		module.</para>
+
+		<para>This proxy module acts like a normal PKCS#11 module, but
+		internally loads a preconfigured set of PKCS#11 modules and
+		coordinates their initialization and finalization. Each slot
+		in the configured modules is exposed as a slot of the
+		<literal>p11-kit</literal> proxy module. The proxy module is
+		then used as a normal PKCS#11 module would be. It can be loaded by
+		crypto libraries like NSS and behaves as expected.</para>
+
+		<para>The proxy module bends the PKCS#11 rules slightly. It does
+		not return the <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
+		error code as specified in PKCS#11. However this is a small
+		price to pay for this compatibility.</para>
+	</section>
+</chapter>
diff --git a/doc/manual/p11-kit-trust.xml b/doc/manual/p11-kit-trust.xml
new file mode 100644
index 0000000..0e06446
--- /dev/null
+++ b/doc/manual/p11-kit-trust.xml
@@ -0,0 +1,112 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="trust">
+<title>Trust Policy Module</title>
+
+	<para>The trust module provides system certificate anchors, blacklists
+	and other trust policy to crypto libraries applications. This
+	information is exposed as PKCS#11 objects.</para>
+
+<section id="trust-files">
+	<title>Files loaded by the Module</title>
+
+	<para>The trust module loads certificates and trust policy information
+	from preconfigured directories and allows them to be looked up via
+	PKCS#11. The directories can be determined with using the following
+	commands:</para>
+
+	<itemizedlist>
+		<listitem>
+		<para>System Anchors: certificates in these locations
+		are automatically treated as certificate authority anchors
+		unless they contain information that prevents that. To check
+		which locations are being used, run the following command:</para>
+<programlisting>
+$ pkg-config --variable p11_system_anchors p11-kit-1
+/etc/pki/tls/certs/ca-bundle.trust.crt:/etc/pki/tls/anchors
+</programlisting>
+		</listitem>
+		<listitem>
+		<para>System Certificates: certificates in these locations
+		are not treated as anchors, but simply made available through
+		the module. To find out which directory is used, run the
+		following command:</para>
+<programlisting>
+$ pkg-config --variable p11_system_certificates p11-kit-1
+/etc/pki/tls/other-certs
+</programlisting>
+		</listitem>
+	</itemizedlist>
+
+	<para>Files in the following formats are supported for loading by the
+	trust policy module:</para>
+
+	<variablelist>
+		<varlistentry>
+			<term>X.509 certificates</term>
+			<listitem><para>X.509 certificates in raw DER format.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term>OpenSSL trust certificates</term>
+			<listitem><para>OpenSSL specific certificates in PEM format
+			that contain trust information. These have a
+			<literal>TRUSTED CERTIFICATE</literal> PEM header. Both
+			trust policy and blacklist information can be loaded
+			from these files.</para></listitem>
+		</varlistentry>
+	</variablelist>
+</section>
+
+<section id="trust-nss">
+	<title>Using the Trust Policy Module with NSS</title>
+
+	<para>The trust policy module is a drop in replacement for the
+	<literal>libnssckbi.so</literal> module and thus works out of
+	the box with NSS. The trust policy module provides NSS style
+	PKCS#11 trust objects for NSS to retrieve.</para>
+
+	<para>The module may be used to replace the
+	<literal>libnssckbi.so</literal> file via an distribution
+	specific alternatives mechanism or otherwise.</para>
+
+	<para>Alternatively NSS applications like Firefox or Thunderbird
+	may be configured to use the trust policy module by adding
+	the <literal>p11-kit-trust.so</literal> PKCS#11 module via their
+	GUI or command line configuration.</para>
+</section>
+
+<section id="trust-glib-networking">
+	<title>Using the Trust Policy Module with glib-networking</title>
+
+	<para>The trust policy module can be used as a source of trust
+	information for glib-networking's <literal>gnutls-pkcs11</literal> backend.
+	The module provides PKCS#11 trust assertion objects as expected.</para>
+
+	<para>The module should work by default if the <literal>gnutls-pkcs11</literal>
+	backend is selected as the glib-networking TLS backend.</para>
+</section>
+
+<section id="trust-disable">
+	<title>Disabling the Trust Policy Module</title>
+
+	<para>This module is installed and enabled by default. It may
+	be disabled in the following ways:</para>
+
+	<itemizedlist>
+		<listitem><para>Use the <option>--disable-trust-module</option>
+		during the <link linkend="devel-building-configure">p11-kit
+		build</link>.</para></listitem>
+		<listitem><para>Disable loading trust policy information
+		from this module by adding a file to <literal>/etc/pkcs11/modules</literal>
+		called <literal>p11-kit-trust.module</literal> containing a
+		<literal>trust-policy:</literal> line.</para></listitem>
+		<listitem><para>Disable this module completely by
+		adding a file to <literal>/etc/pkcs11/modules</literal>
+		called <literal>p11-kit-trust.module</literal> containing a
+		<literal>enable-in:</literal> line.</para></listitem>
+	</itemizedlist>
+
+</section>
+
+</chapter>
diff --git a/doc/manual/p11-kit.xml b/doc/manual/p11-kit.xml
new file mode 100644
index 0000000..5242b1a
--- /dev/null
+++ b/doc/manual/p11-kit.xml
@@ -0,0 +1,229 @@
+<?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="p11-kit">
+
+<refentryinfo>
+	<title>p11-kit</title>
+	<productname>p11-kit</productname>
+	<authorgroup>
+		<author>
+			<contrib>Maintainer</contrib>
+			<firstname>Stef</firstname>
+			<surname>Walter</surname>
+			<email>stef@thewalter.net</email>
+		</author>
+	</authorgroup>
+</refentryinfo>
+
+<refmeta>
+	<refentrytitle>p11-kit</refentrytitle>
+	<manvolnum>8</manvolnum>
+	<refmiscinfo class="manual">System Commands</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+	<refname>p11-kit</refname>
+	<refpurpose>Tool for operating on configured PKCS#11 modules</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>p11-kit list-modules</command>
+	</cmdsynopsis>
+	<cmdsynopsis>
+		<command>p11-kit extract</command> <arg choice="plain">--filter=&lt;what&gt;</arg>
+			<arg choice="plain">--format=&lt;type&gt;</arg> /path/to/destination
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>Description</title>
+	<para><command>p11-kit</command> is a command line tool that
+	can be used to perform operations on PKCS#11 modules configured on the
+	system.</para>
+
+	<para>See the various sub commands below. The following global options
+	can be used:</para>
+
+	<variablelist>
+		<varlistentry>
+			<term><option>-v, --verbose</option></term>
+			<listitem><para>Run in verbose mode with debug
+			output.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term><option>-q, --quiet</option></term>
+			<listitem><para>Run in quiet mode without warning or
+			failure messages.</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+</refsect1>
+
+<refsect1>
+	<title>List Modules</title>
+
+	<para>List system configured PKCS#11 modules.</para>
+
+<programlisting>
+$ p11-kit list-modules
+</programlisting>
+
+	<para>The modules, information about them and the tokens present in
+	the PKCS#11 modules will be displayed.</para>
+
+</refsect1>
+
+<refsect1>
+	<title>Extract</title>
+
+	<para>Extract certificates from configured PKCS#11 modules.</para>
+
+<programlisting>
+$ p11-kit extract --format=x509-directory --filter=ca-certificates /path/to/directory
+</programlisting>
+
+	<para>You can specify the following options to control what to extract.
+	The <option>--filter</option> and <option>--format</option> arguments
+	should be specified. By default this command will not overwrite the
+	destination file or directory.</para>
+
+	<variablelist>
+		<varlistentry>
+			<term><option>--filter=&lt;what&gt;</option></term>
+			<listitem><para>Specifies what certificates to export.
+			You can specify the following values:
+			<variablelist>
+				<varlistentry>
+					<term><option>ca-anchors</option></term>
+					<listitem><para>Certificate anchors (default)</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>blacklist</option></term>
+					<listitem><para>Blacklisted certificates</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>certificates</option></term>
+					<listitem><para>All certificates</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>pkcs11:object=xx</option></term>
+					<listitem><para>A PKCS#11 URI</para></listitem>
+				</varlistentry>
+			</variablelist>
+			</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term><option>--format=&lt;type&gt;</option></term>
+			<listitem><para>The format of the destination file or directory.
+			You can specify one of the following values:
+			<variablelist>
+				<varlistentry>
+					<term><option>x509-file</option></term>
+					<listitem><para>DER X.509 certificate file</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>x509-directory</option></term>
+					<listitem><para>directory of X.509 certificates</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>pem-bundle</option></term>
+					<listitem><para>File containing one or more certificate PEM blocks</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>pem-directory</option></term>
+					<listitem><para>Directory PEM files each containing one certifiacte</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>openssl-bundle</option></term>
+					<listitem><para>OpenSSL specific PEM bundle of certificates</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>openssl-directory</option></term>
+					<listitem><para>Directory of OpenSSL specific PEM files</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>java-cacerts</option></term>
+					<listitem><para>Java keystore 'cacerts' certificate bundle</para></listitem>
+				</varlistentry>
+			</variablelist>
+			</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term><option>--overwrite</option></term>
+			<listitem><para>Overwrite output file or directory.</para></listitem>
+		</varlistentry>
+		<varlistentry>
+			<term><option>--purpose=&lt;usage&gt;</option></term>
+			<listitem><para>Limit to certificates usable for the given purpose
+			You can specify one of the following values:
+			<variablelist>
+				<varlistentry>
+					<term><option>server-auth</option></term>
+					<listitem><para>For authenticating servers</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>client-auth</option></term>
+					<listitem><para>For authenticating clients</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>email</option></term>
+					<listitem><para>For email protection</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>code-signing</option></term>
+					<listitem><para>For authenticated signed code</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><option>1.2.3.4.5...</option></term>
+					<listitem><para>An arbitrary purpose OID</para></listitem>
+				</varlistentry>
+			</variablelist>
+			</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+</refsect1>
+
+<refsect1>
+	<title>Extract Trust</title>
+
+	<para>Extract standard trust information files.</para>
+
+<programlisting>
+$ p11-kit extract-trust
+</programlisting>
+
+	<para>OpenSSL, GnuTLS and Java cannot currently read trust information
+	directly from the trust policy module. This command extracts trust
+	information such as certificate anchors for use by these libraries.</para>
+
+	<para>What this command does, and where it extracts the files is
+	distribution or site specific. Packagers or administrators are expected
+	customize this command.</para>
+
+</refsect1>
+
+<refsect1>
+  <title>Bugs</title>
+  <para>
+    Please send bug reports to either the distribution bug tracker
+    or the upstream bug tracker at
+    <ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit">https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit</ulink>.
+  </para>
+</refsect1>
+
+<refsect1>
+  <title>See also</title>
+    <simplelist type="inline">
+        <member><citerefentry><refentrytitle>pkcs11.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+    </simplelist>
+    <para>
+    Further details available in the p11-kit online documentation at
+    <ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>.
+  </para>
+</refsect1>
+
+</refentry>
diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml
new file mode 100644
index 0000000..3146f60
--- /dev/null
+++ b/doc/manual/pkcs11.conf.xml
@@ -0,0 +1,207 @@
+<?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="pkcs11.conf">
+
+<refentryinfo>
+	<title>pkcs11.conf</title>
+	<productname>p11-kit</productname>
+	<authorgroup>
+		<author>
+			<contrib>Maintainer</contrib>
+			<firstname>Stef</firstname>
+			<surname>Walter</surname>
+			<email>stef@thewalter.net</email>
+		</author>
+	</authorgroup>
+</refentryinfo>
+
+<refmeta>
+	<refentrytitle>pkcs11.conf</refentrytitle>
+	<manvolnum>5</manvolnum>
+	<refmiscinfo class="manual">System Files</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+	<refname>pkcs11.conf</refname>
+	<refpurpose>Configuration files for PKCS#11 modules</refpurpose>
+</refnamediv>
+
+<refsect1>
+	<title>Description</title>
+	<para>The <command>pkcs11.conf</command> configuration files are a standard
+	way to configure PKCS#11 modules.</para>
+</refsect1>
+
+<refsect1 id="config-format">
+	<title>File format</title>
+	<para>A complete configuration consists of several files. These files are
+	text files. Since <literal>p11-kit</literal> is built to be used in all
+	sorts of environments and at very low levels of the software stack, we
+	cannot make use of high level configuration APIs that you may find on a
+	modern desktop.</para>
+
+	<para>Each setting in the config file is specified consists of a name and
+	a value. The name is a simple string consisting of characters and dashes.
+	The name consists of alpha numeric characters, dot, hyphen and
+	underscore.</para>
+
+	<para>The value is specified after the name on the same line, separated
+	from it by a <literal>:</literal> (colon). White space between the
+	name and value is ignored.</para>
+
+	<para>Blank lines are ignored. White space at the beginning or end of
+	lines is stripped. Lines that begin with a <literal>#</literal> character
+	are ignored as comments. Comments are not recognized when they come after
+	a value on a line.</para>
+
+	<para>A fictitious module configuration file might look like:</para>
+<programlisting>
+module: module.so
+# Here is a comment
+
+managed: true
+setting.2: A long value with text.
+x-custom : text
+</programlisting>
+</refsect1>
+
+<refsect1 id="config-module">
+	<title>Module Configuration</title>
+
+	<para>Each configured PKCS#11 module has its own config file. These files
+	can be <link linkend="config-locations">placed in various locations</link>.</para>
+	<para>The filename of the configuration file may consist of upper and lowercase letters
+	underscore, comma, dash and dots. The first characters needs to be an alphanumeric,
+	the filename should end with a <literal>.module</literal> extension.</para>
+	<para>Most importantly each config file specifies the path of the PKCS#11 module to
+	load. A module config file has the following fields:</para>
+
+	<variablelist>
+	<varlistentry>
+		<term><option>module:</option></term>
+		<listitem>
+			<para>The filename of the PKCS#11 module to load.
+			This should include an extension like <literal>.so</literal></para>
+			<para>If this value is blank, then the module will be ignored.
+			This can be used in the user configs to override loading of a module
+			specified in the system configuration.</para>
+
+			<para>If this is a relative path, then the module will be loaded
+			from the <link linkend="devel-paths-modules">default module directory</link>.</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term><option>critical:</option></term>
+		<listitem>
+			<para>Set to <literal>yes</literal> if the module is critical and
+			required to load. If a critical module fails to load or initialize,
+			then the loading process for all registered modules will abort and
+			return an error code.</para>
+
+			<para>This argument is optional and defaults to <literal>no</literal>.</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term><option>enable-in:</option></term>
+		<listitem>
+			<para>A comma and/or space separated list of names of programs that
+			this module should only be loaded in. The module will not be loaded
+			for other programs using p11-kit. The base name of the process executable
+			should be used here, for example
+			<literal>seahorse, ssh</literal>.</para>
+			<para>This is not a security feature. The argument is optional. If
+			not present, then any process will load the module.</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term><option>disable-in:</option></term>
+		<listitem>
+			<para>A comma and/or space separated list of names of programs that
+			this module should not be loaded in. The module will be loaded for any
+			other programs using p11-kit. The base name of the process
+			executable should be used here, for example
+			<literal>firefox, thunderbird-bin</literal>.</para>
+			<para>This is not a security feature. The argument is optional. If
+			not present, then any process will load the module.</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
+		<term><option>trust-policy:</option></term>
+		<listitem>
+			<para>If this setting is present then this module is used to load
+			trust policy information such as certificate anchors and black lists.
+			The value should be an integer. Modules with a lower number are loaded
+			first. Trust policy information in modules loaded later overrides
+			those loaded first.</para>
+		</listitem>
+	</varlistentry>
+	</variablelist>
+
+	<para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal>
+	for the same module.</para>
+
+	<para>Other fields may be present, but it is recommended that field names
+	that are not specified in this document start with a <literal>x-</literal>
+	prefix.</para>
+</refsect1>
+
+<refsect1 id="config-global">
+	<title>Global Configuration</title>
+
+	<para>A global configuration may also be present. This file contains settings
+	that are not related to a single PKCS#11 module. The location(s) of the
+	global configuration are described below. The global configuration file
+	can contain the following fields:</para>
+
+	<variablelist>
+	<varlistentry>
+		<term><option>user-config:</option></term>
+		<listitem><para>This will be equal to one of the following values:
+		<literal>none</literal>, <literal>merge</literal>,
+		<literal>only</literal>.</para></listitem>
+	</varlistentry>
+	</variablelist>
+
+	<para>Other fields may be present, but it is recommended that field names
+	that are not specified in this document start with a <literal>x-</literal>
+	prefix.</para>
+</refsect1>
+
+<refsect1 id="config-locations">
+	<title>Configuration Files</title>
+
+	<para>Each configured PKCS#11 module is has its own config file. These
+	files are placed in a directory. In addition a global config file exists.
+	There is a system configuration consisting of the various module config
+	files and a file for global configuration. Optionally each user can provide
+	additional configuration or override the system configuration.</para>
+
+	<para>The system global configuration file is usually in
+	<literal>/etc/pkcs11/pkcs11.conf</literal> and the user global
+	configuration file is in <literal>~/.pkcs11/pkcs11.conf</literal> in the
+	user's home directory.</para>
+
+	<para>The module config files are usually located in the
+	<literal>/etc/pkcs11/modules</literal> directory, with one configuration
+	file per module. In addition the <literal>~/.pkcs11/modules</literal> directory
+	can be used for modules installed by the user.</para>
+
+	<para>The default system config file and module directory can be changed
+	when building p11-kit. Always
+	<link linkend="devel-paths">lookup these paths</link> using
+	<literal>pkg-config</literal>.</para>
+</refsect1>
+
+<refsect1>
+	<title>See also</title>
+	<simplelist type="inline">
+		<member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+	</simplelist>
+	<para>Further details available in the p11-kit online documentation at
+	<ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>.
+	</para>
+</refsect1>
+
+</refentry>
diff --git a/doc/manual/style.css b/doc/manual/style.css
new file mode 100644
index 0000000..3d0f951
--- /dev/null
+++ b/doc/manual/style.css
@@ -0,0 +1,116 @@
+@import url("gtk-doc.css");
+
+TABLE.navigation {
+	background-color: #f9b631 !important;
+	border-width: 0 !important;
+	color: white;
+	font-family: Georgia, "Times New Roman", Times, serif;
+	height: 4em !important;
+}
+
+TABLE.navigation TH {
+	font-size: 30pt !important;
+	font-weight: normal;
+	text-align: left !important;
+	padding-left: 10pt;
+}
+
+TABLE.navigation TH:first-child {
+	padding-left: 40pt;
+}
+
+.shortcuts {
+	color: white !important;
+}
+
+.shortcuts a {
+	color: white !important;
+	font-family: Verdana, Arial, 'Bitstream Vera Sans', Helvetica, sans-serif;
+}
+
+P.title {
+	font-size: 30pt !important;
+}
+
+BODY {
+	padding-top: 5.5em !important;
+}
+
+DIV.book,
+DIV.refentry,
+DIV.chapter,
+DIV.index,
+DIV.footer,
+DIV.section {
+	font-family: Verdana, Arial, 'Bitstream Vera Sans', Helvetica, sans-serif;
+	font-size: 9.5pt;
+	line-height: 150%;
+}
+
+BODY > DIV.book,
+BODY > DIV.footer {
+	margin-left: 1em;
+	margin-right: 1em;
+}
+
+BODY > DIV.refentry,
+BODY > DIV.chapter,
+BODY > DIV.index,
+BODY > DIV.section {
+	margin-left: 3em;
+	margin-right: 1em;
+}
+
+DIV.variablelist TABLE {
+	font-size: 9.5pt;
+	line-height: 150%;
+}
+
+DIV.refsect1,
+DIV.refsect2,
+DIV.refsynopsisdiv {
+	margin-bottom: 3em !important;
+}
+
+H1 {
+	position: relative;
+	left: -1em;
+	font-weight: normal !important;
+}
+
+H2 {
+	position: relative;
+	left: -1em;
+	font-weight: normal !important;
+}
+
+H3 {
+	position: relative;
+	left: -1em;
+	font-weight: normal !important;
+}
+
+CODE.option {
+	white-space: nowrap;
+}
+
+DIV.toc DL {
+	margin-top: 0;
+	margin-bottom: 0;
+}
+
+DIV.book > DIV.toc > DL > DT {
+	margin-top: 1em;
+}
+
+DIV.toc DT {
+	margin-bottom: 0.3em;
+}
+
+TABLE.variablelist SPAN.term {
+	padding-right: 1em;
+}
+
+DIV.cmdsynopsis {
+	font-family: monospace;
+}
diff --git a/doc/manual/version.xml.in b/doc/manual/version.xml.in
new file mode 100644
index 0000000..27323da
--- /dev/null
+++ b/doc/manual/version.xml.in
@@ -0,0 +1 @@
+@VERSION@
\ No newline at end of file