doc/book.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY manref SYSTEM "manref.xml">
   8      <!ENTITY gpl2 SYSTEM "gpl-2.0.xml">
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <book>
  13  <bookinfo>
  14   <title>MP-XQuery - User's Guide and Reference</title>
  15   <authorgroup>
  16    <author>
  17     <firstname>Adam</firstname><surname>Dickmeiss</surname>
  18    </author>
  19   </authorgroup>
  20   <releaseinfo>&version;</releaseinfo>
  21   <copyright>
  22    <year>2014-2015</year>
  23    <holder>Index Data</holder>
  24   </copyright>
  25   <abstract>
  26    <simpara>
  27     This manual is part of MP-XQuery version &version;.
  28     </simpara>
  29    <simpara>
  30     MP-XQuery is a Metaproxy module that allows record conversion
  31     using W3C's XQuery language.
  32    </simpara>
  33    <simpara>
  34     MP-XQuery is covered by the GNU General Public License version 2.
  35    </simpara>
  36    <simpara>
  37     <inlinemediaobject>
  38      <imageobject>
  39       <imagedata fileref="common/id.png" format="PNG"/>
  40      </imageobject>
  41      <imageobject>
  42       <imagedata fileref="common/id.eps" format="EPS"/>
  43      </imageobject>
  44     </inlinemediaobject>
  45    </simpara>
  46   </abstract>
  47  </bookinfo>
  48  <chapter id="introduction">
  49   <title>Introduction</title>
  50   <para>
  51    MP-XQuery is a <ulink url="&url.metaproxy;">Metaproxy</ulink> module
  52    that allows record conversion using
  53    <ulink url="http://www.w3.org/TR/xquery/">W3C XML XQuery</ulink>.
  54    The initial motivations for the module was to be able to
  55    <ulink url="http://bibframe.org">BIBFRAME</ulink> records
  56    via SRU/Z39.50. By using the
  57    <ulink
  58        url="https://github.com/lcnetdev/marc2bibframe">
  59     marc2bibframe
  60     </ulink> utilities, this module can convert existing
  61     MARCXML records to BIBFRAME records - on the fly - as part of retrieval.
  62   </para>
  63  </chapter>
  64  <chapter id="installation">
  65   <title>Installation</title>
  66   <para>
  67    MP-XQuery is available as packages for CentOS/RHEL 6 and most recent
  68    Ubuntu/Debian versions. For other systems, the module must be build
  69    from source.
  70   </para>
  71   <sect1 id="installation.packages">
  72    <title>Installing packages</title>
  73    <para>
  74     You need to enable the relevant software repositories.
  75     For setting up refer to one of:
  76     <ulink
  77         url="http://ftp.indexdata.dk/pub/mp-xquery/redhat/centos/6/README">CentOS 6</ulink>
  78     ,
  79     <ulink
  80         url="http://ftp.indexdata.dk/pub/mp-xquery/redhat/centos/7/README">CentOS 7</ulink>
  81     ,
  82     <ulink
  83         url="http://ftp.indexdata.dk/pub/mp-xquery/ubuntu/README">Ubuntu</ulink>
  84     and
  85     <ulink
  86         url="http://ftp.indexdata.dk/pub/mp-xquery/debian/README">Debian</ulink>
  87    </para>
  88    <para>
  89     The package is called <literal>mp-xquery</literal> on RHEL/Debian systems.
  90     Install that package and you are ready to use filter "xquery" in your
  91     setup.
  92    </para>
  93   </sect1>
  94   <sect1 id="installation.source">
  95    <title>Installing from source</title>
  96    <para>
  97     To build from source, you need zorba and metaproxy development
  98     packages. <ulink url="http://www.zorba.io">Zorba</ulink>
  99     might be installed in <filename>/opt/zorba</filename> as follows:
 100     <screen>
 101     tar zxf zorba-3.0.tar.gz
 102     cd zorba-3.0
 103     mkdir build
 104     cd build
 105     cmake -Wno-dev \
 106         -D CMAKE_INSTALL_PREFIX=/opt/zorba \
 107         -D ZORBA_SUPPRESS_SWIG:BOOL=ON  \
 108         ..
 109     sudo make install
 110     </screen>
 111     Consult the Zorba documentation for more information.
 112    </para>
 113    <para>
 114     Metaproxy can be installed as follows:
 115     <screen>
 116      ./configure
 117      make
 118      sudo make install
 119     </screen>
 120     But consult the Metaproxy documentation for requirements and
 121     options.
 122    </para>
 123    <para>
 124     We are now ready to build the MP-XQuery module with:
 125     <screen>
 126      cd mp-xquery-version
 127      make ZORBA=/opt/zorba MP_CONFIG=/usr/local/bin/mp-config
 128     </screen>
 129     Adjust <literal>ZORBA</literal> and <literal>MP_CONFIG</literal> values
 130     above for the correct location of installed
 131     Zorba and Metaproxy's mp-config respectively. MP_CONFIG can be omitted
 132     if Metaproxy was installed in the system PATH.
 133    </para>
 134    <para>
 135     You can now install the <filename>metaproxy_filter_xquery.so</filename>
 136     in a directory searched by Metaproxy daemon.
 137     Specifically, that's the directories
 138     given by the <literal>dlpath</literal> configuration.
 139    </para>
 140    <para>
 141     If dlpath includes <filename>/usr/lib/metaproxy6/modules</filename>,
 142     the module can be installed with:
 143     <screen>
 144      cp src/metaproxy_filter_xquery.so /usr/lib/metaproxy6/modules
 145     </screen>
 146    </para>
 147    <note>
 148     <para>
 149      For RHEL/CentOS systems on 64-bit architectures, the correct paths is:
 150      <filename>/usr/lib64/metaproxy6/modules</filename>.
 151     </para>
 152    </note>
 153   </sect1>
 154   <sect1>
 155    <title>BIBFRAME</title>
 156    <para>
 157     The MARC to BIBFRAME was the primary purpose of the XQuery
 158     module for Metaproxy, but generally the module is a just an alternative
 159     to record_transform filter of Metaproxy which primarily performs XSLT.
 160    </para>
 161    <para>
 162     The <filename>bibframe directory</filename> of the source tar
 163     contains sample file for performing MARC to BIBFRAME conversions.
 164     Upon <literal>make install</literal> these are installed to directory
 165     <filename>/usr/share/mp-xquery/bibframe</filename> and they are also
 166     part of the package <literal>mp-xquery</literal>.
 167    </para>
 168    <para>
 169     <literal>config.xml</literal> is a complete Metaproxy configuration file.
 170     It includes a standalone configuration that makes Metaproxy offe
 171     Z39.50 and SRU support on port 9070. The modules in use are http_file
 172     (to serve XSL files), sru_z3950 (SRU service), cql_rpn (CQL to RPN
 173     conversion), xquery (to convert MARCXML to BIBFRAME), record_transform
 174     (to convert MARC21 to MARCXML), virt_db (for database rewrite), log
 175     (to perform backend logging) and, finally, z3950_client to interface
 176     a Z39.50 target.
 177    </para>
 178    <para>
 179     It is important that the XQuery module comes before the
 180     "record_transform" so that the XQuery module sees XML
 181     <emphasis>only</emphasis> and not ISO2709-records.
 182     If it does, they will be ignored (passed through) by the XQuery module.
 183    </para>
 184    <para>
 185     The XQuery module script name points to the full path of
 186     <filename>zorba3-0.xqy</filename> part
 187     of marc2bibframe . Do not move <filename>zorba3-0.xqy</filename>
 188     from its place within the
 189     marc2bibframe directory as other files are referred to and their relative
 190     location must be preserved.
 191    </para>
 192    <para>
 193     File <filename>cql2pqf.txt</filename> contains a simple DC/CQL profile
 194     for driving a CQL to RPN conversion.
 195     It is referred to from the cql_rpn filter in config.xml .
 196    </para>
 197    <para>
 198     File <filename>explain.xml</filename> is SRU explain configuration.
 199     It is referred to from the sru_z3950 filter in config.xml .
 200    </para>
 201    <para>
 202     Directory <filename>xsl/..</filename> is client side XSL for brief -
 203     and full display. These must be located so that the http_file filter
 204     can fetch them. For example, if these files are located in
 205     <filename>/usr/share/mp-xquery/bibframe/xsl</filename> , then
 206     http_file would hold
 207     <screen><![CDATA[
 208       <filter type="http_file">
 209         <area>
 210           <documentroot>/usr/share/mp-xquery/bibframe/xsl</documentroot>
 211           <prefix></prefix>
 212           <passthru>true</passthru>
 213         </area>
 214       </filter>
 215 ]]>
 216     </screen>
 217    </para>
 218    <note>
 219     <para>
 220      Do not modify the files below <filename>/usr/share/mp-xquery</filename>.
 221      They will be  overwritten by a package update and if
 222      <literal>make install</literal> is executed.
 223      Use them if they can be used as-is but copy them away if you want to
 224      modify them (such as <filename>config.xml</filename>).
 225     </para>
 226    </note>
 227   </sect1>
 228  </chapter>
 229  <reference id="reference">
 230   <title>Reference</title>
 231    <partintro id="reference-introduction">
 232     <para>
 233      The material in this chapter is drawn directly from the individual
 234      manual entries.
 235     </para>
 236    </partintro>
 237    &manref;
 238  </reference>
 239
 240  <appendix id="license">
 241   <title>License</title>
 242   <para>
 243    Copyright (C) 2014-2015 Index Data
 244   </para>
 245
 246   <para>
 247    Metaproxy is free software; you can redistribute it and/or modify it under
 248    the terms of the GNU General Public License as published by the Free
 249    Software Foundation; either version 2, or (at your option) any later
 250    version.
 251    </para>
 252
 253   <para>
 254    Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
 255    WARRANTY; without even the implied warranty of MERCHANTABILITY or
 256    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 257    for more details.
 258   </para>
 259
 260   <para>
 261    You should have received a copy of the GNU General Public License
 262    along with Metaproxy; see the file LICENSE.  If not, write to the
 263    Free Software Foundation,
 264    51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 265    </para>
 266
 267  </appendix>
 268
 269  &gpl2;
 270 </book>
 271
 272 <!-- Keep this comment at the end of the file
 273 Local variables:
 274 mode: nxml
 275 nxml-child-indent: 1
 276 End:
 277 -->