doc/recordmodel-domxml.xml

   1 <chapter id="record-model-domxml">
   2   <!-- $Id: recordmodel-domxml.xml,v 1.16 2007-08-13 08:53:42 adam Exp $ -->
   3   <title>&acro.dom; &acro.xml; Record Model and Filter Module</title>
   4
   5   <para>
   6    The record model described in this chapter applies to the fundamental,
   7    structured &acro.xml;
   8    record type <literal>&acro.dom;</literal>, introduced in
   9    <xref linkend="componentmodulesdom"/>. The &acro.dom; &acro.xml; record model
  10    is experimental, and its inner workings might change in future
  11    releases of the &zebra; Information Server.
  12   </para>
  13
  14
  15
  16   <section id="record-model-domxml-filter">
  17    <title>&acro.dom; Record Filter Architecture</title>
  18
  19      <para>
  20       The &acro.dom; &acro.xml; filter uses a standard &acro.dom; &acro.xml; structure as
  21       internal data model, and can therefore parse, index, and display
  22       any &acro.xml; document type. It is well suited to work on
  23       standardized &acro.xml;-based formats such as Dublin Core, MODS, METS,
  24       MARCXML, OAI-PMH, RSS, and performs equally  well on any other
  25       non-standard &acro.xml; format.
  26     </para>
  27     <para>
  28       A parser for binary &acro.marc; records based on the ISO2709 library
  29       standard is provided, it transforms these to the internal
  30       &acro.marcxml; &acro.dom; representation. Other binary document parsers
  31       are planned to follow.
  32     </para>
  33
  34     <para>
  35       The &acro.dom; filter architecture consists of four
  36       different pipelines, each being a chain of arbitrarily many successive
  37       &acro.xslt; transformations of the internal &acro.dom; &acro.xml;
  38       representations of documents.
  39     </para>
  40
  41     <figure id="record-model-domxml-architecture-fig">
  42       <title>&acro.dom; &acro.xml; filter architecture</title>
  43       <mediaobject>
  44        <imageobject>
  45          <imagedata fileref="domfilter.pdf" format="PDF" scale="50"/>
  46         </imageobject>
  47         <imageobject>
  48           <imagedata fileref="domfilter.png" format="PNG"/>
  49         </imageobject>
  50         <textobject>
  51         <!-- Fall back if none of the images can be used -->
  52         <phrase>
  53           [Here there should be a diagram showing the &acro.dom; &acro.xml;
  54            filter architecture, but is seems that your
  55            tool chain has not been able to include the diagram in this
  56            document.]
  57          </phrase>
  58         </textobject>
  59       </mediaobject>
  60      </figure>
  61
  62
  63     <table id="record-model-domxml-architecture-table" frame="top">
  64       <title>&acro.dom; &acro.xml; filter pipelines overview</title>
  65       <tgroup cols="5">
  66        <thead>
  67         <row>
  68          <entry>Name</entry>
  69          <entry>When</entry>
  70          <entry>Description</entry>
  71          <entry>Input</entry>
  72          <entry>Output</entry>
  73         </row>
  74        </thead>
  75
  76        <tbody>
  77         <row>
  78          <entry><literal>input</literal></entry>
  79          <entry>first</entry>
  80          <entry>input parsing and initial
  81           transformations to common &acro.xml; format</entry>
  82          <entry>Input raw &acro.xml; record buffers, &acro.xml;  streams and
  83                 binary &acro.marc; buffers</entry>
  84          <entry>Common &acro.xml; &acro.dom;</entry>
  85         </row>
  86         <row>
  87          <entry><literal>extract</literal></entry>
  88          <entry>second</entry>
  89          <entry>indexing term extraction
  90           transformations</entry>
  91          <entry>Common &acro.xml; &acro.dom;</entry>
  92          <entry>Indexing &acro.xml; &acro.dom;</entry>
  93         </row>
  94         <row>
  95          <entry><literal>store</literal></entry>
  96          <entry>second</entry>
  97          <entry> transformations before internal document
  98           storage</entry>
  99          <entry>Common &acro.xml; &acro.dom;</entry>
 100          <entry>Storage &acro.xml; &acro.dom;</entry>
 101         </row>
 102         <row>
 103          <entry><literal>retrieve</literal></entry>
 104          <entry>third</entry>
 105          <entry>multiple document retrieve transformations from
 106           storage to different output
 107           formats are possible</entry>
 108          <entry>Storage &acro.xml; &acro.dom;</entry>
 109          <entry>Output &acro.xml; syntax in requested formats</entry>
 110         </row>
 111        </tbody>
 112       </tgroup>
 113      </table>
 114
 115     <para>
 116       The &acro.dom; &acro.xml; filter pipelines use &acro.xslt; (and if  supported on
 117       your platform, even &acro.exslt;), it brings thus full &acro.xpath;
 118       support to the indexing, storage and display rules of not only
 119       &acro.xml; documents, but also binary &acro.marc; records.
 120     </para>
 121    </section>
 122
 123
 124    <section id="record-model-domxml-pipeline">
 125     <title>&acro.dom; &acro.xml; filter pipeline configuration</title>
 126
 127    <para>
 128     The experimental, loadable  &acro.dom; &acro.xml;/&acro.xslt; filter module
 129    <literal>mod-dom.so</literal>
 130     is invoked by the <filename>zebra.cfg</filename> configuration statement
 131     <screen>
 132      recordtype.xml: dom.db/filter_dom_conf.xml
 133     </screen>
 134     In this example the &acro.dom; &acro.xml; filter is configured to work
 135     on all data files with suffix
 136     <filename>*.xml</filename>, where the configuration file is found in the
 137     path <filename>db/filter_dom_conf.xml</filename>.
 138    </para>
 139
 140    <para>The &acro.dom; &acro.xslt; filter configuration file must be
 141     valid &acro.xml;. It might look like this:
 142     <screen>
 143     <![CDATA[
 144     <?xml version="1.0" encoding="UTF8"?>
 145     <dom xmlns="http://indexdata.com/zebra-2.0">
 146       <input>
 147         <xmlreader level="1"/>
 148         <!-- <marc inputcharset="marc-8"/> -->
 149       </input>
 150       <extract>
 151          <xslt stylesheet="common2index.xsl"/>
 152       </extract>
 153       <store>
 154          <xslt stylesheet="common2store.xsl"/>
 155       </store>
 156       <retrieve name="dc">
 157         <xslt stylesheet="store2dc.xsl"/>
 158       </retrieve>
 159       <retrieve name="mods">
 160         <xslt stylesheet="store2mods.xsl"/>
 161       </retrieve>
 162     </dom>
 163     ]]>
 164     </screen>
 165    </para>
 166    <para>
 167      The root &acro.xml; element <literal>&lt;dom&gt;</literal> and all other &acro.dom;
 168      &acro.xml; filter elements are residing in the namespace
 169      <literal>xmlns="http://indexdata.com/zebra-2.0"</literal>.
 170    </para>
 171    <para>
 172     All pipeline definition elements - i.e. the
 173      <literal>&lt;input&gt;</literal>,
 174      <literal>&lt;extract&gt;</literal>,
 175      <literal>&lt;store&gt;</literal>, and
 176      <literal>&lt;retrieve&gt;</literal> elements - are optional.
 177      Missing pipeline definitions are just interpreted
 178      do-nothing identity pipelines.
 179    </para>
 180    <para>
 181     All pipeline definition elements may contain zero or more
 182     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 183     &acro.xslt; transformation instructions, which are performed
 184     sequentially from top to bottom.
 185     The paths in the <literal>stylesheet</literal> attributes
 186     are relative to zebras working directory, or absolute to the file
 187     system root.
 188    </para>
 189
 190
 191    <section id="record-model-domxml-pipeline-input">
 192     <title>Input pipeline</title>
 193    <para>
 194     The <literal>&lt;input&gt;</literal> pipeline definition element
 195     may contain either one &acro.xml; Reader definition
 196     <literal><![CDATA[<xmlreader level="1"/>]]></literal>, used to split
 197     an &acro.xml; collection input stream into individual &acro.xml; &acro.dom;
 198     documents at the prescribed element level,
 199     or one &acro.marc; binary
 200     parsing instruction
 201     <literal><![CDATA[<marc inputcharset="marc-8"/>]]></literal>, which defines
 202     a conversion to &acro.marcxml; format &acro.dom; trees. The allowed values
 203     of the <literal>inputcharset</literal> attribute depend on your
 204     local <productname>iconv</productname> set-up.
 205    </para>
 206    <para>
 207     Both input parsers deliver individual &acro.dom; &acro.xml; documents to the
 208     following chain of zero or more
 209     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 210     &acro.xslt; transformations. At the end of this pipeline, the documents
 211     are in the common format, used to feed both the
 212      <literal>&lt;extract&gt;</literal> and
 213      <literal>&lt;store&gt;</literal> pipelines.
 214    </para>
 215    </section>
 216
 217    <section id="record-model-domxml-pipeline-extract">
 218     <title>Extract pipeline</title>
 219      <para>
 220        The <literal>&lt;extract&gt;</literal> pipeline takes documents
 221        from any common &acro.dom; &acro.xml; format to the &zebra; specific
 222         indexing &acro.dom; &acro.xml; format.
 223        It may consist of zero ore more
 224        <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 225        &acro.xslt; transformations, and the outcome is handled to the
 226        &zebra; core to drive the process of building the inverted
 227        indexes. See
 228        <xref linkend="record-model-domxml-canonical-index"/> for
 229        details.
 230      </para>
 231    </section>
 232
 233    <section id="record-model-domxml-pipeline-store">
 234     <title>Store pipeline</title>
 235        The <literal>&lt;store&gt;</literal> pipeline takes documents
 236        from any common &acro.dom;  &acro.xml; format to the &zebra; specific
 237         storage &acro.dom;  &acro.xml; format.
 238        It may consist of zero ore more
 239        <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 240        &acro.xslt; transformations, and the outcome is handled to the
 241        &zebra; core for deposition into the internal storage system.
 242     </section>
 243
 244    <section id="record-model-domxml-pipeline-retrieve">
 245     <title>Retrieve pipeline</title>
 246     <para>
 247       Finally, there may be one or more
 248       <literal>&lt;retrieve&gt;</literal> pipeline definitions, each
 249       of them again consisting of zero or more
 250       <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 251        &acro.xslt; transformations. These are used for document
 252       presentation after search, and take the internal storage &acro.dom;
 253       &acro.xml; to the requested output formats during record present
 254       requests.
 255     </para>
 256     <para>
 257      The  possible multiple
 258      <literal>&lt;retrieve&gt;</literal> pipeline definitions
 259      are distinguished by their unique <literal>name</literal>
 260      attributes, these are the literal <literal>schema</literal> or
 261      <literal>element set</literal> names used in
 262       <ulink url="http://www.loc.gov/standards/sru/srw/">&acro.srw;</ulink>,
 263       <ulink url="&url.sru;">&acro.sru;</ulink> and
 264       &acro.z3950; protocol queries.
 265    </para>
 266    </section>
 267
 268
 269    <section id="record-model-domxml-canonical-index">
 270     <title>Canonical Indexing Format</title>
 271
 272     <para>
 273      &acro.dom; &acro.xml; indexing comes in two flavors: pure
 274      processing-instruction governed plain &acro.xml; documents, and - very
 275      similar to the Alvis filter indexing format - &acro.xml; documents
 276      containing &acro.xml; <literal>&lt;record&gt;</literal> and
 277      <literal>&lt;index&gt;</literal> instructions from the magic
 278      namespace <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>.
 279     </para>
 280
 281    <section id="record-model-domxml-canonical-index-pi">
 282     <title>Processing-instruction governed indexing format</title>
 283
 284       <para>The output of the processing instruction driven
 285       indexing &acro.xslt; stylesheets must contain
 286       processing instructions named
 287        <literal>zebra-2.0</literal>.
 288       The output of the &acro.xslt; indexing transformation is then
 289       parsed using &acro.dom; methods, and the contained instructions are
 290       performed on the <emphasis>elements and their
 291       subtrees directly following the processing instructions</emphasis>.
 292       </para>
 293       <para>
 294      For example, the output of the command
 295      <screen>
 296        xsltproc dom-index-pi.xsl marc-one.xml
 297      </screen>
 298      might look like this:
 299      <screen>
 300       <![CDATA[
 301       <?xml version="1.0" encoding="UTF-8"?>
 302       <?zebra-2.0 record id=11224466 rank=42?>
 303       <record>
 304         <?zebra-2.0 index control:0?>
 305         <control>11224466</control>
 306         <?zebra-2.0 index any:w title:w title:p title:s?>
 307         <title>How to program a computer</title>
 308       </record>
 309       ]]>
 310      </screen>
 311     </para>
 312    </section>
 313
 314    <section id="record-model-domxml-canonical-index-element">
 315     <title>Magic element governed indexing format</title>
 316
 317     <para>The output of the indexing &acro.xslt; stylesheets must contain
 318     certain elements in the magic
 319      <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>
 320     namespace. The output of the &acro.xslt; indexing transformation is then
 321     parsed using &acro.dom; methods, and the contained instructions are
 322     performed on the <emphasis>magic elements and their
 323     subtrees</emphasis>.
 324     </para>
 325     <para>
 326     For example, the output of the command
 327      <screen>
 328       xsltproc dom-index-element.xsl marc-one.xml
 329      </screen>
 330      might look like this:
 331      <screen>
 332       <![CDATA[
 333       <?xml version="1.0" encoding="UTF-8"?>
 334       <z:record xmlns:z="http://indexdata.com/zebra-2.0"
 335                 z:id="11224466" z:rank="42">
 336           <z:index name="control:0">11224466</z:index>
 337           <z:index name="any:w title:w title:p title:s">
 338                     How to program a computer</z:index>
 339       </z:record>
 340       ]]>
 341      </screen>
 342     </para>
 343    </section>
 344
 345
 346    <section id="record-model-domxml-canonical-index-semantics">
 347     <title>Semantics of the indexing formats</title>
 348
 349     <para>
 350      Both indexing formats are defined with equal semantics and
 351      behavior in mind:
 352      <itemizedlist>
 353        <listitem>
 354          <para>&zebra; specific instructions are either
 355          processing instructions named
 356          <literal>zebra-2.0</literal> or
 357          elements contained in the namespace
 358          <literal>xmlns:z="http://indexdata.com/zebra-2.0"</literal>.
 359          </para>
 360        </listitem>
 361        <listitem>
 362          <para>There must be exactly one <literal>record</literal>
 363            instruction, which sets the scope for the following,
 364            possibly nested <literal>index</literal> instructions.
 365          </para>
 366        </listitem>
 367        <listitem>
 368          <para>
 369             The unique <literal>record</literal> instruction
 370             may have additional attributes <literal>id</literal>,
 371             <literal>rank</literal> and <literal>type</literal>.
 372             Attribute <literal>id</literal> is the value of the opaque ID
 373             and may be any string not containing the whitespace character
 374             <literal>' '</literal>.
 375             The <literal>rank</literal> attribute value must be a
 376             non-negative integer. See
 377             <xref linkend="administration-ranking"/> .
 378             The <literal>type</literal> attribute specifies how the record
 379             is to be treated. The following values may be given for
 380             <literal>type</literal>:
 381             <variablelist>
 382              <varlistentry>
 383               <term><literal>insert</literal></term>
 384               <listitem>
 385                <para>
 386                 The record is inserted. If the record already exists, it is
 387                 skipped (i.e. not replaced).
 388                </para>
 389               </listitem>
 390              </varlistentry>
 391              <varlistentry>
 392               <term><literal>replace</literal></term>
 393               <listitem>
 394                <para>
 395                 The record is replaced. If the record does not already exist,
 396                 it is skipped (i.e. not inserted).
 397                </para>
 398               </listitem>
 399              </varlistentry>
 400              <varlistentry>
 401               <term><literal>delete</literal></term>
 402               <listitem>
 403                <para>
 404                 The record is deleted. If the record does not already exist,
 405                 it is skipped (i.e. nothing is deleted).
 406                </para>
 407               </listitem>
 408              </varlistentry>
 409              <varlistentry>
 410               <term><literal>update</literal></term>
 411               <listitem>
 412                <para>
 413                 The record is inserted or replaced depending on whether the
 414                 record exists or not. This is the default behavior but may
 415                 be effectively changed by "outside" the scope of the DOM
 416                 filter by zebraidx commands or extended services updates.
 417                </para>
 418               </listitem>
 419              </varlistentry>
 420             </variablelist>
 421           Note that the value of <literal>type</literal> is only used to
 422           determine the action if and only if the Zebra indexer is running
 423           in "update" mode (i.e zebraidx update) or if the specialUpdate
 424           action of the
 425           <link linkend="administration-extended-services-z3950">Extended
 426           Service Update</link> is used.
 427           For this reason a specialUpdate may end up deleting records!
 428          </para>
 429        </listitem>
 430        <listitem>
 431          <para> Multiple and possible nested <literal>index</literal>
 432          instructions must contain at least one
 433          <literal>indexname:indextype</literal>
 434          pair, and may contain multiple such pairs separated by the
 435          whitespace character  <literal>' '</literal>. In each index
 436          pair, the name and the type of the index is separated by a
 437          colon character <literal>':'</literal>.
 438          </para>
 439        </listitem>
 440        <listitem>
 441          <para>
 442          Any index name consisting of ASCII letters, and following the
 443          standard &zebra; rules will do, see
 444          <xref linkend="querymodel-pqf-apt-mapping-accesspoint"/>.
 445          </para>
 446        </listitem>
 447        <listitem>
 448          <para>
 449          Index types are restricted to the values defined in
 450          the standard configuration
 451          file <filename>default.idx</filename>, see
 452          <xref linkend="querymodel-bib1"/> and
 453          <xref linkend="fields-and-charsets"/> for details.
 454          </para>
 455        </listitem>
 456        <listitem>
 457          <para>
 458          &acro.dom; input documents which are not resulting in both one
 459          unique valid
 460          <literal>record</literal> instruction and one or more valid
 461          <literal>index</literal> instructions can not be searched and
 462          found. Therefore,
 463          invalid document processing is aborted, and any content of
 464          the <literal>&lt;extract&gt;</literal> and
 465          <literal>&lt;store&gt;</literal> pipelines is discarted.
 466           A warning is issued in the logs.
 467          </para>
 468        </listitem>
 469       </itemizedlist>
 470     </para>
 471
 472     <para>The examples work as follows:
 473      From the original &acro.xml; file
 474      <literal>marc-one.xml</literal> (or from the &acro.xml; record &acro.dom; of the
 475      same form coming from an <literal>&lt;input&gt;</literal>
 476      pipeline),
 477      the indexing
 478      pipeline <literal>&lt;extract&gt;</literal>
 479      produces an indexing &acro.xml; record, which is defined by
 480      the <literal>record</literal> instruction
 481      &zebra; uses the content of
 482      <literal>z:id="11224466"</literal>
 483      or
 484      <literal>id=11224466</literal>
 485      as internal
 486      record ID, and - in case static ranking is set - the content of
 487      <literal>rank=42</literal>
 488      or
 489      <literal>z:rank="42"</literal>
 490      as static rank.
 491     </para>
 492
 493
 494     <para>In these examples, the following literal indexes are constructed:
 495      <screen>
 496        any:w
 497        control:0
 498        title:w
 499        title:p
 500        title:s
 501      </screen>
 502      where the indexing type is defined after the
 503      literal <literal>':'</literal> character.
 504      Any value from the standard configuration
 505      file <filename>default.idx</filename> will do.
 506      Finally, any
 507      <literal>text()</literal> node content recursively contained
 508      inside the <literal>&lt;z:index&gt;</literal> element, or any
 509      element following a <literal>index</literal> processing instruction,
 510      will be filtered through the
 511      appropriate char map for character normalization, and will be
 512      inserted in the named indexes.
 513     </para>
 514     <para>
 515      Finally, this example configuration can be queried using &acro.pqf;
 516      queries, either transported by &acro.z3950;, (here using a yaz-client)
 517      <screen>
 518       <![CDATA[
 519       Z> open localhost:9999
 520       Z> elem dc
 521       Z> form xml
 522       Z>
 523       Z> find @attr 1=control @attr 4=3 11224466
 524       Z> scan @attr 1=control @attr 4=3 ""
 525       Z>
 526       Z> find @attr 1=title program
 527       Z> scan @attr 1=title ""
 528       Z>
 529       Z> find @attr 1=title @attr 4=2 "How to program a computer"
 530       Z> scan @attr 1=title @attr 4=2 ""
 531       ]]>
 532      </screen>
 533      or the proprietary
 534      extensions <literal>x-pquery</literal> and
 535      <literal>x-pScanClause</literal> to
 536      &acro.sru;, and &acro.srw;
 537      <screen>
 538       <![CDATA[
 539       http://localhost:9999/?version=1.1&operation=searchRetrieve&x-pquery=@attr 1=title program
 540       http://localhost:9999/?version=1.1&operation=scan&x-pScanClause=@attr 1=title ""
 541       ]]>
 542      </screen>
 543      See <xref linkend="zebrasrv-sru"/> for more information on &acro.sru;/&acro.srw;
 544      configuration, and <xref linkend="gfs-config"/> or the &yaz;
 545      <ulink url="&url.yaz.cql;">&acro.cql; section</ulink>
 546      for the details or the &yaz; frontend server.
 547     </para>
 548     <para>
 549      Notice that there are no <filename>*.abs</filename>,
 550      <filename>*.est</filename>, <filename>*.map</filename>, or other &acro.grs1;
 551      filter configuration files involves in this process, and that the
 552      literal index names are used during search and retrieval.
 553     </para>
 554     <para>
 555      In case that we want to support the usual
 556      <literal>bib-1</literal> &acro.z3950; numeric access points, it is a
 557      good idea to choose string index names defined in the default
 558      configuration file <filename>tab/bib1.att</filename>, see
 559      <xref linkend="attset-files"/>
 560     </para>
 561
 562    </section>
 563
 564    </section>
 565   </section>
 566
 567
 568   <section id="record-model-domxml-conf">
 569    <title>&acro.dom; Record Model Configuration</title>
 570
 571
 572   <section id="record-model-domxml-index">
 573    <title>&acro.dom; Indexing Configuration</title>
 574     <para>
 575      As mentioned above, there can be only one indexing pipeline,
 576      and configuration of the indexing process is a synonym
 577      of writing an &acro.xslt; stylesheet which produces &acro.xml; output containing the
 578      magic processing instructions or elements discussed in
 579      <xref linkend="record-model-domxml-canonical-index"/>.
 580      Obviously, there are million of different ways to accomplish this
 581      task, and some comments and code snippets are in order to
 582      enlighten the wary.
 583     </para>
 584     <para>
 585      Stylesheets can be written in the <emphasis>pull</emphasis> or
 586      the <emphasis>push</emphasis> style: <emphasis>pull</emphasis>
 587      means that the output &acro.xml; structure is taken as starting point of
 588      the internal structure of the &acro.xslt; stylesheet, and portions of
 589      the input &acro.xml; are <emphasis>pulled</emphasis> out and inserted
 590      into the right spots of the output &acro.xml; structure.
 591      On the other
 592      side, <emphasis>push</emphasis> &acro.xslt; stylesheets are recursively
 593      calling their template definitions, a process which is commanded
 594      by the input &acro.xml; structure, and is triggered to produce
 595      some output &acro.xml;
 596      whenever some special conditions in the input stylesheets are
 597      met. The <emphasis>pull</emphasis> type is well-suited for input
 598      &acro.xml; with strong and well-defined structure and semantics, like the
 599      following &acro.oai; indexing example, whereas the
 600      <emphasis>push</emphasis> type might be the only possible way to
 601      sort out deeply recursive input &acro.xml; formats.
 602     </para>
 603     <para>
 604      A <emphasis>pull</emphasis> stylesheet example used to index
 605      &acro.oai; harvested records could use some of the following template
 606      definitions:
 607      <screen>
 608       <![CDATA[
 609       <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 610        xmlns:z="http://indexdata.com/zebra-2.0"
 611        xmlns:oai="http://www.openarchives.org/&acro.oai;/2.0/"
 612        xmlns:oai_dc="http://www.openarchives.org/&acro.oai;/2.0/oai_dc/"
 613        xmlns:dc="http://purl.org/dc/elements/1.1/"
 614        version="1.0">
 615
 616        <!-- Example pull and magic element style Zebra indexing -->
 617        <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 618
 619         <!-- disable all default text node output -->
 620         <xsl:template match="text()"/>
 621
 622         <!-- disable all default recursive element node transversal -->
 623         <xsl:template match="node()"/>
 624
 625          <!-- match only on oai xml record root -->
 626          <xsl:template match="/">
 627           <z:record z:id="{normalize-space(oai:record/oai:header/oai:identifier)}">
 628            <!-- you may use z:rank="{some XSLT; function here}" -->
 629
 630            <!-- explicetly calling defined templates -->
 631            <xsl:apply-templates/>
 632           </z:record>
 633          </xsl:template>
 634
 635          <!-- OAI indexing templates -->
 636          <xsl:template match="oai:record/oai:header/oai:identifier">
 637           <z:index name="oai_identifier:0">
 638            <xsl:value-of select="."/>
 639           </z:index>
 640          </xsl:template>
 641
 642          <!-- etc, etc -->
 643
 644          <!-- DC specific indexing templates -->
 645          <xsl:template match="oai:record/oai:metadata/oai_dc:dc/dc:title">
 646           <z:index name="dc_any:w dc_title:w dc_title:p dc_title:s ">
 647            <xsl:value-of select="."/>
 648           </z:index>
 649          </xsl:template>
 650
 651          <!-- etc, etc -->
 652
 653       </xsl:stylesheet>
 654       ]]>
 655      </screen>
 656     </para>
 657   </section>
 658
 659
 660   <section id="record-model-domxml-index-marc">
 661    <title>&acro.dom; Indexing &acro.marcxml;</title>
 662     <para>
 663       The &acro.dom; filter allows indexing of both binary &acro.marc; records
 664       and &acro.marcxml; records, depending on its configuration.
 665       A typical &acro.marcxml; record might look like this:
 666       <screen>
 667       <![CDATA[
 668       <record xmlns="http://www.loc.gov/MARC21/slim">
 669        <rank>42</rank>
 670        <leader>00366nam  22001698a 4500</leader>
 671        <controlfield tag="001">   11224466   </controlfield>
 672        <controlfield tag="003">DLC  </controlfield>
 673        <controlfield tag="005">00000000000000.0  </controlfield>
 674        <controlfield tag="008">910710c19910701nju           00010 eng    </controlfield>
 675        <datafield tag="010" ind1=" " ind2=" ">
 676          <subfield code="a">   11224466 </subfield>
 677        </datafield>
 678        <datafield tag="040" ind1=" " ind2=" ">
 679          <subfield code="a">DLC</subfield>
 680          <subfield code="c">DLC</subfield>
 681        </datafield>
 682        <datafield tag="050" ind1="0" ind2="0">
 683          <subfield code="a">123-xyz</subfield>
 684        </datafield>
 685        <datafield tag="100" ind1="1" ind2="0">
 686          <subfield code="a">Jack Collins</subfield>
 687        </datafield>
 688        <datafield tag="245" ind1="1" ind2="0">
 689          <subfield code="a">How to program a computer</subfield>
 690        </datafield>
 691        <datafield tag="260" ind1="1" ind2=" ">
 692          <subfield code="a">Penguin</subfield>
 693        </datafield>
 694        <datafield tag="263" ind1=" " ind2=" ">
 695          <subfield code="a">8710</subfield>
 696        </datafield>
 697        <datafield tag="300" ind1=" " ind2=" ">
 698          <subfield code="a">p. cm.</subfield>
 699        </datafield>
 700       </record>
 701       ]]>
 702       </screen>
 703     </para>
 704
 705     <para>
 706       It is easily possible to make string manipulation in the &acro.dom;
 707       filter. For example, if you want to drop some leading articles
 708       in the indexing of sort fields, you might want to pick out the
 709       &acro.marcxml; indicator attributes to chop of leading substrings. If
 710       the above &acro.xml; example would have an indicator
 711       <literal>ind2="8"</literal> in the title field
 712       <literal>245</literal>, i.e.
 713       <screen>
 714       <![CDATA[
 715        <datafield tag="245" ind1="1" ind2="8">
 716          <subfield code="a">How to program a computer</subfield>
 717        </datafield>
 718       ]]>
 719       </screen>
 720       one could write a template taking into account this information
 721       to chop the first <literal>8</literal> characters from the
 722       sorting index <literal>title:s</literal> like this:
 723       <screen>
 724       <![CDATA[
 725       <xsl:template match="m:datafield[@tag='245']">
 726         <xsl:variable name="chop">
 727           <xsl:choose>
 728             <xsl:when test="not(number(@ind2))">0</xsl:when>
 729             <xsl:otherwise><xsl:value-of select="number(@ind2)"/></xsl:otherwise>
 730           </xsl:choose>
 731         </xsl:variable>
 732
 733         <z:index name="title:w title:p any:w">
 734            <xsl:value-of select="m:subfield[@code='a']"/>
 735         </z:index>
 736
 737         <z:index name="title:s">
 738           <xsl:value-of select="substring(m:subfield[@code='a'], $chop)"/>
 739         </z:index>
 740
 741       </xsl:template>
 742       ]]>
 743       </screen>
 744       The output of the above &acro.marcxml; and &acro.xslt; excerpt would then be:
 745       <screen>
 746       <![CDATA[
 747         <z:index name="title:w title:p any:w">How to program a computer</z:index>
 748         <z:index name="title:s">program a computer</z:index>
 749       ]]>
 750       </screen>
 751       and the record would be sorted in the title index under 'P', not 'H'.
 752     </para>
 753   </section>
 754
 755
 756   <section id="record-model-domxml-index-wizzard">
 757    <title>&acro.dom; Indexing Wizardry</title>
 758     <para>
 759      The names and types of the indexes can be defined in the
 760      indexing &acro.xslt; stylesheet <emphasis>dynamically according to
 761      content in the original &acro.xml; records</emphasis>, which has
 762      opportunities for great power and wizardry as well as grande
 763      disaster.
 764     </para>
 765     <para>
 766      The following excerpt of a <emphasis>push</emphasis> stylesheet
 767      <emphasis>might</emphasis>
 768      be a good idea according to your strict control of the &acro.xml;
 769      input format (due to rigorous checking against well-defined and
 770      tight RelaxNG or &acro.xml; Schema's, for example):
 771      <screen>
 772       <![CDATA[
 773       <xsl:template name="element-name-indexes">
 774        <z:index name="{name()}:w">
 775         <xsl:value-of select="'1'"/>
 776        </z:index>
 777       </xsl:template>
 778       ]]>
 779      </screen>
 780      This template creates indexes which have the name of the working
 781      node of any input  &acro.xml; file, and assigns a '1' to the index.
 782      The example query
 783      <literal>find @attr 1=xyz 1</literal>
 784      finds all files which contain at least one
 785      <literal>xyz</literal> &acro.xml; element. In case you can not control
 786      which element names the input files contain, you might ask for
 787      disaster and bad karma using this technique.
 788     </para>
 789     <para>
 790      One variation over the theme <emphasis>dynamically created
 791      indexes</emphasis> will definitely be unwise:
 792      <screen>
 793       <![CDATA[
 794       <!-- match on oai xml record root -->
 795       <xsl:template match="/">
 796        <z:record>
 797
 798         <!-- create dynamic index name from input content -->
 799         <xsl:variable name="dynamic_content">
 800          <xsl:value-of select="oai:record/oai:header/oai:identifier"/>
 801         </xsl:variable>
 802
 803         <!-- create zillions of indexes with unknown names -->
 804         <z:index name="{$dynamic_content}:w">
 805          <xsl:value-of select="oai:record/oai:metadata/oai_dc:dc"/>
 806         </z:index>
 807        </z:record>
 808
 809       </xsl:template>
 810       ]]>
 811      </screen>
 812      Don't be tempted to play too smart tricks with the power of
 813      &acro.xslt;, the above example will create zillions of
 814      indexes with unpredictable names, resulting in severe &zebra;
 815      index pollution..
 816     </para>
 817   </section>
 818
 819   <section id="record-model-domxml-debug">
 820    <title>Debuggig &acro.dom; Filter Configurations</title>
 821    <para>
 822     It can be very hard to debug a &acro.dom; filter setup due to the many
 823     sucessive &acro.marc; syntax translations, &acro.xml; stream splitting and
 824     &acro.xslt; transformations involved. As an aid, you have always the
 825     power of the <literal>-s</literal> command line switch to the
 826     <literal>zebraidz</literal> indexing command at your hand:
 827     <screen>
 828      zebraidx -s -c zebra.cfg update some_record_stream.xml
 829     </screen>
 830     This command line simulates indexing and dumps a lot of debug
 831     information in the logs, telling exactly which transformations
 832     have been applied, how the documents look like after each
 833     transformation, and which record ids and terms are send to the indexer.
 834    </para>
 835   </section>
 836
 837   <!--
 838   <section id="record-model-domxml-elementset">
 839    <title>&acro.dom; Exchange Formats</title>
 840    <para>
 841      An exchange format can be anything which can be the outcome of an
 842      &acro.xslt; transformation, as far as the stylesheet is registered in
 843      the main &acro.dom; &acro.xslt; filter configuration file, see
 844      <xref linkend="record-model-domxml-filter"/>.
 845      In principle anything that can be expressed in  &acro.xml;, HTML, and
 846      TEXT can be the output of a <literal>schema</literal> or
 847     <literal>element set</literal> directive during search, as long as
 848      the information comes from the
 849      <emphasis>original input record &acro.xml; &acro.dom; tree</emphasis>
 850      (and not the transformed and <emphasis>indexed</emphasis> &acro.xml;!!).
 851     </para>
 852     <para>
 853      In addition, internal administrative information from the &zebra;
 854      indexer can be accessed during record retrieval. The following
 855      example is a summary of the possibilities:
 856      <screen>
 857       <![CDATA[
 858       <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 859        xmlns:z="http://indexdata.com/zebra-2.0"
 860        version="1.0">
 861
 862        <!- - register internal zebra parameters - ->
 863        <xsl:param name="id" select="''"/>
 864        <xsl:param name="filename" select="''"/>
 865        <xsl:param name="score" select="''"/>
 866        <xsl:param name="schema" select="''"/>
 867
 868        <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 869
 870        <!- - use then for display of internal information - ->
 871        <xsl:template match="/">
 872          <z:zebra>
 873            <id><xsl:value-of select="$id"/></id>
 874            <filename><xsl:value-of select="$filename"/></filename>
 875            <score><xsl:value-of select="$score"/></score>
 876            <schema><xsl:value-of select="$schema"/></schema>
 877          </z:zebra>
 878        </xsl:template>
 879
 880       </xsl:stylesheet>
 881       ]]>
 882      </screen>
 883     </para>
 884
 885   </section>
 886   -->
 887
 888   <!--
 889   <section id="record-model-domxml-example">
 890    <title>&acro.dom; Filter &acro.oai; Indexing Example</title>
 891    <para>
 892      The source code tarball contains a working &acro.dom; filter example in
 893      the directory <filename>examples/dom-oai/</filename>, which
 894      should get you started.
 895     </para>
 896     <para>
 897      More example data can be harvested from any &acro.oai; compliant server,
 898      see details at the  &acro.oai;
 899      <ulink url="http://www.openarchives.org/">
 900       http://www.openarchives.org/</ulink> web site, and the community
 901       links at
 902      <ulink url="http://www.openarchives.org/community/index.html">
 903       http://www.openarchives.org/community/index.html</ulink>.
 904      There is a  tutorial
 905      found at
 906      <ulink url="http://www.oaforum.org/tutorial/">
 907       http://www.oaforum.org/tutorial/</ulink>.
 908     </para>
 909    </section>
 910    -->
 911
 912   </section>
 913
 914
 915  </chapter>
 916
 917
 918
 919  <!-- Keep this comment at the end of the file
 920  Local variables:
 921  mode: sgml
 922  sgml-omittag:t
 923  sgml-shorttag:t
 924  sgml-minimize-attributes:nil
 925  sgml-always-quote-attributes:t
 926  sgml-indent-step:1
 927  sgml-indent-data:t
 928  sgml-parent-document: "zebra.xml"
 929  sgml-local-catalogs: nil
 930  sgml-namecase-general:t
 931  End:
 932  -->