doc/recordmodel-domxml.xml

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