Add documentation about the configuration paths

 * Default module path
 * How to lookup paths using pkg-config

5 files changed, 76 insertions, 15 deletions

diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index 76b3fa2..7c28f86 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -40,9 +40,11 @@ user-config: merge
 
 <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.
-module: /usr/lib/my-pkcs11-module.so
+# 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.
@@ -110,20 +112,22 @@ critical: yes
 	<section id="config-module">
 		<title>Module Configuration</title>
 
-		<para>Each configured PKCS#11 module has its own config file. The
-		location(s) of these files are described below. Most importantly each
-		config file specifies the location of the PKCS#11 module to load. Each
-		module config file has the following fields:</para>
+		<para>Each configured PKCS#11 module has its own config file. These files
+		can be <link linkend="config-locations">placed in various locations</link>.
+		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>module:</term>
 				<listitem>
-					<para>The absolute path to the PKCS#11 module to load.
+					<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="notes-paths-modules">default module directory</link>.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>
@@ -174,16 +178,19 @@ critical: yes
 		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 in
+		<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 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 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="notes-paths">lookup these paths</link> using
+		<literal>pkg-config</literal>.</para>
 	</section>
 </chapter>
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index 1bfb571..8e8c933 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -13,6 +13,7 @@
 
 	<xi:include href="p11-kit-config.xml"/>
 	<xi:include href="p11-kit-sharing.xml"/>
+	<xi:include href="p11-kit-notes.xml"/>
 
 	<chapter xml:id="reference">
 		<title>Reference</title>
diff --git a/doc/p11-kit-notes.xml b/doc/p11-kit-notes.xml
new file mode 100644
index 0000000..e030824
--- /dev/null
+++ b/doc/p11-kit-notes.xml
@@ -0,0 +1,48 @@
+<?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>Developer and Packager Notes</title>
+
+	<section id="notes-paths">
+		<title>Using pkg-config to determine paths</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="notes-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_system_config_modules</command>
+/etc/pkcs11/modules</programlisting>
+		</section>
+
+		<section id="notes-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>
+
+</chapter>
diff --git a/doc/p11-kit.xml b/doc/p11-kit.xml
index a040da8..3c8a318 100644
--- a/doc/p11-kit.xml
+++ b/doc/p11-kit.xml
@@ -33,5 +33,8 @@
 	<xi:include href="p11-kit-config.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
 		<xi:fallback/>
 	</xi:include>
+	<xi:include href="p11-kit-notes.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+		<xi:fallback/>
+	</xi:include>
 
 </article>
diff --git a/doc/style.css b/doc/style.css
index 67ffff3..a4aa19e 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -79,5 +79,7 @@ H2 {
 }
 
 H3 {
+	position: relative;
+	left: -1em;
 	font-weight: normal !important;
 }