Add section about enabling the configuration

[mp-sparql-moved-to-github.git] / doc / book.xml

diff --git a/doc/book.xml b/doc/book.xml
index f1dbe0b..852994c 100644 (file)
--- a/doc/book.xml
+++ b/doc/book.xml
@@ -86,6 +86,14 @@
     Install that package and you are ready to use filter "sparql" in your
     setup.
    </para>
+   <para>
+    mp-sparql depends on a number of packages created by Index Data and
+    system-provided ones, such as Libxml2. For external software Zorba, no
+    system package exist so Index Data has packaged that separately. This
+    package is called <literal>idzorba</literal>. All these dependences should
+    be automatically installed when the Index Data software repository is
+    set up.
+   </para>
   </sect1>
   <sect1 id="installation.source">
    <title>Installing from source</title>
@@ -97,8 +105,7 @@
      make
      sudo make install
     </screen>
-    But consult the Metaproxy documentation for requirements and
-    options.
+    Refer to the Metaproxy documentation for requirements and options.
    </para>
    <para>
     We are now ready to build the MP-SPARQL module with:
@@ -131,6 +138,84 @@
     </para>
    </note>
   </sect1>
+  <sect1>
+   <title>Configuration</title>
+   <para>
+    If you have installed mp-sparql as a package or have executed
+    <literal>make install</literal> from source, sample configuration
+    can be found in <filename>/usr/share/mp-sparql/bibframe</filename> or
+    <filename>/usr/local/share/mp-sparql/bibframe</filename>. In the
+    the following /usr/share prefix assumed. Adjust accordingly.
+    The directory contains these files:
+    <variablelist>
+     <varlistentry>
+      <term><filename>triplestore.xml</filename></term>
+      <listitem>
+       <para>
+       A mature PQF to SPARQL configuration illustrating a lot of the
+       configuration facilities that are described in the manual
+       page of <xref linkend="sparql"/>.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><filename>config-sparql.xml</filename></term>
+      <listitem>
+       <para>
+       A full metaproxy configuration file that includes
+       <filename>triplestore.xml</filename> cofiguration for the
+       mp-sparql filter, enables SRU and CQL to PQF conversion.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
+      <term><filename>filter-sparql.xml</filename></term>
+      <listitem>
+       <para>
+       A partial metaproxy configuration suitable to be enabled in
+       <filename>/etc/metaproxy/filters-enabled</filename>.
+       This includes <filename>triplestore.xml</filename> as well.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+   <para>
+    If you want to use the package layout and modular configuration we
+    suggest you use filter-sparql.xml and perform something along the lines of:
+    <screen>
+     cp /usr/share/mp-sparql/bibframe/filter-sparql.xml /etc/metaproxy/filters-available
+     cp /usr/share/mp-sparql/bibframe/triplestore.xml /etc/metaproxy
+     sudo vi /etc/metaproxy/triplestore.xml
+     ln -s ../filters-available/filter-sparql.xml /etc/metaproxy/filters-enabled
+     service metaproxy restart
+    </screen>
+    A copy of triplestore.xml is made. Adjust the
+    <literal>&lt;defaults uri=.. </literal> value to the URI of your
+    triplestore.
+   </para>
+   <para>
+    If you want to create your own top-level configuration, you can copy
+    <filename>config-sparql.xml</filename> to any location you like and
+    run metaproxy with that. Something like this:
+    <screen>
+     mkdir /etc/myconfig
+     cp /usr/share/mp-sparql/bibframe/* /etc/myconfig
+     sudo vi /etc/myconfig/triplestore.xml
+     metaproxy -c /etc/myconfig/config-sparql.xml
+    </screen>
+    Again, a copy of triplestore.xml is made. Adjust the
+    <literal>&lt;defaults uri=.. </literal> value to the URI of your
+    triplestore.
+   </para>
+   <note>
+    <para>
+     Do not edit files in <filename>/usr/share/mp-sparql/bibframe</filename>.
+     They are only samples and will be overwritten by a package update.
+     Instead copy the files away from there if you need to modify them.
+    </para>
+   </note>
+  </sect1>
  </chapter>
  <reference id="reference">
   <title>Reference</title>