doc/recordmodel-domxml.xml

   1 <chapter id="record-model-domxml">
   2   <!-- $Id: recordmodel-domxml.xml,v 1.8 2007-02-21 15:03:30 marc Exp $ -->
   3   <title>&dom; &xml; Record Model and Filter Module</title>
   4
   5   <para>
   6    The record model described in this chapter applies to the fundamental,
   7    structured &xml;
   8    record type <literal>dom</literal>, introduced in
   9    <xref linkend="componentmodulesdom"/>. The &dom; &xml; record model
  10    is experimental, and it's 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>&dom; Record Filter Architecture</title>
  18
  19      <para>
  20       The &dom; &xml; filter uses a standard &dom; &xml; structure as
  21       internal data model, and can therefore parse, index, and display
  22       any &xml; document type. It is wellsuited to work on
  23       standardized &xml;-based formats such as Dublin Core, MODS, METS,
  24       MARCXML, OAI-PMH, RSS, and performs equally  well on any other
  25       non-standard &xml; format.
  26     </para>
  27     <para>
  28       A parser for binary &marc; records based on the ISO2709 library
  29       standard is provided, it transforms these to the internal
  30       &marcxml; &dom; representation. Other binary document parsers
  31       are planned to follow.
  32     </para>
  33
  34     <para>
  35       The &dom; filter architecture consists of four
  36       different pipelines, each being a chain of arbitraily many sucessive
  37       &xslt; transformations of the internal &dom; &xml;
  38       representations of documents.
  39     </para>
  40
  41     <figure id="record-model-domxml-architecture-fig">
  42       <title>&dom; &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 &dom; &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>&dom; &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 &xml; format</entry>
  82          <entry>Input raw &xml; record buffers, &xml;  streams and
  83                 binary &marc; buffers</entry>
  84          <entry>Common &xml; &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 &xml; &dom;</entry>
  92          <entry>Indexing &xml; &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 &xml; &dom;</entry>
 100          <entry>Storage &xml; &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 &xml; &dom;</entry>
 109          <entry>Output &xml; syntax in requested formats</entry>
 110         </row>
 111        </tbody>
 112       </tgroup>
 113      </table>
 114
 115     <para>
 116       The &dom; &xml; filter pipelines use &xslt; (and if  supported on
 117       your platform, even &exslt;), it brings thus full &xpath;
 118       support to the indexing, storage and display rules of not only
 119       &xml; documents, but also binary &marc; records.
 120     </para>
 121    </section>
 122
 123
 124    <section id="record-model-domxml-pipeline">
 125     <title>&dom; &xml; filter pipeline configuration</title>
 126
 127    <para>
 128     The experimental, loadable  &dom; &xml;/&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 &dom; &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 &dom; &xslt; filter configuration file must be
 141     valid &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       <extrac>
 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 &xml; element <literal>&lt;dom&gt;</literal> and all other &dom;
 168      &xml; filter elements are residing in the namespace
 169      <literal>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;extact&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 pipeine definition elements may contain zero or more
 182     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 183     &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 &xml; Reader definition
 196     <literal><![CDATA[<xmlreader level="1"/>]]></literal>, used to split
 197     an &xml; collection input stream into individual &xml; &dom;
 198     documents at the prescribed element level,
 199     or one &marc; binary
 200     parsing instruction
 201     <literal><![CDATA[<marc inputcharset="marc-8"/>]]></literal>, which defines
 202     a conversion to &marcxml; format &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 &dom; &xml; documents to the
 208     following chain of zero or more
 209     <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 210     &xslt; transformations. At the end of this pipeline, the documents
 211     are in the common format, used to feed both the
 212      <literal>&lt;extact&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;extact&gt;</literal> pipeline takes documents
 221        from any common &dom; &xml; format to the &zebra; specific
 222         indexing &dom; &xml; format.
 223        It may consist of zero ore more
 224        <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 225        &xslt; transformations, and the outcome is handled to the
 226        &zebra; core to drive the proces 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 &dom; &xml; format to the &zebra; specific
 237         storage &dom; &xml; format.
 238        It may consist of zero ore more
 239        <literal><![CDATA[<xslt stylesheet="path/file.xsl"/>]]></literal>
 240        &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        &xslt; transformations. These are used for document
 252       presentation after search, and take the internal storage &dom;
 253       &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/">&srw;</ulink>,
 263       <ulink url="&url.sru;">&sru;</ulink> and
 264       &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      &dom; &xml; indexing comes in two flavors: pure
 274      processing-instruction governed plain &xml; documents, and - very
 275      similar to the Alvis filter indexing format - &xml; documents
 276      containing &xml; <literal>&lt;record&gt;</literal> and
 277      <literal>&lt;index&gt;</literal> instructions from the magic
 278      namespace <literal>xmlns:z="http://indexdata.dk/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 &xslt; stylesheets must contain
 286       processing instructions named
 287        <literal>zebra-2.0</literal>.
 288       The output of the &xslt; indexing transformation is then
 289       parsed using &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:w?>
 305         <control>11224466</control>
 306         <?zebra-2.0 index title:w title:p title:s any:w?>
 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 &xslt; stylesheets must contain
 318     certain elements in the magic
 319      <literal>xmlns:z="http://indexdata.dk/zebra-2.0"</literal>
 320     namespace. The output of the &xslt; indexing transformation is then
 321     parsed using &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">11224466</z:index>
 337           <z:index name="title:w title:p title:s any:w">
 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      behaviour in mind.
 352     </para>
 353
 354
 355     <para>This means the following: From the original &xml; file
 356      <literal>one-record.xml</literal> (or from the &xml; record &dom; of the
 357      same form coming from a splitted input file), the indexing
 358      stylesheet produces an indexing &xml; record, which is defined by
 359      the <literal>record</literal> element in the magic namespace
 360      <literal>xmlns:z="http://indexdata.dk/zebra/xslt/1"</literal>.
 361      &zebra; uses the content of
 362      <literal>z:id="oai:JTRS:CP-3290---Volume-I"</literal> as internal
 363      record ID, and - in case static ranking is set - the content of
 364      <literal>z:rank="47896"</literal> as static rank. Following the
 365      discussion in <xref linkend="administration-ranking"/>
 366      we see that this records is internally ordered
 367      lexicographically according to the value of the string
 368      <literal>oai:JTRS:CP-3290---Volume-I47896</literal>.
 369      The type of action performed during indexing is defined by
 370      <literal>z:type="update"&gt;</literal>, with recognized values
 371      <literal>insert</literal>, <literal>update</literal>, and
 372      <literal>delete</literal>.
 373     </para>
 374
 375
 376     <para>In these examples, the following literal indexes are constructed:
 377      <screen>
 378        any:w
 379        control:w
 380        title:w
 381        title:p
 382        title:s
 383      </screen>
 384      where the indexing type is defined after the
 385      literal <literal>':'</literal> charaacter.
 386      Any value from the standard configuration
 387      file <filename>default.idx</filename> will do.
 388      Finally, any
 389      <literal>text()</literal> node content recursively contained
 390      inside the <literal>&lt;z:index&gt;</literal> element, or any
 391      element following a <literal>index</literal> processing instruction,
 392      will be filtered through the
 393      appropriate charmap for character normalization, and will be
 394      inserted in the named indexes.
 395     </para>
 396
 397
 398     <para>
 399      Specific to this example, we see that the single word
 400      <literal>oai:JTRS:CP-3290---Volume-I</literal> will be literal,
 401      byte for byte without any form of character normalization,
 402      inserted into the index named <literal>oai:identifier</literal>,
 403      the text
 404      <literal>Kumar Krishen and *Calvin Burnham, Editors</literal>
 405      will be inserted using the <literal>w</literal> character
 406      normalization defined in <filename>default.idx</filename> into
 407      the index <literal>dc:creator</literal> (that is, after character
 408      normalization the index will keep the inidividual words
 409      <literal>kumar</literal>, <literal>krishen</literal>,
 410      <literal>and</literal>, <literal>calvin</literal>,
 411      <literal>burnham</literal>, and <literal>editors</literal>), and
 412      finally both the texts
 413      <literal>Proceedings of the 4th International Conference and Exhibition:
 414       World Congress on Superconductivity - Volume I</literal>
 415      and
 416      <literal>Kumar Krishen and *Calvin Burnham, Editors</literal>
 417      will be inserted into the index <literal>dc:all</literal> using
 418      the same character normalization map <literal>w</literal>.
 419     </para>
 420     <para>
 421      Finally, this example configuration can be queried using &pqf;
 422      queries, either transported by &z3950;, (here using a yaz-client)
 423      <screen>
 424       <![CDATA[
 425       Z> open localhost:9999
 426       Z> elem dc
 427       Z> form xml
 428       Z>
 429       Z> f @attr 1=dc_creator Kumar
 430       Z> scan @attr 1=dc_creator adam
 431       Z>
 432       Z> f @attr 1=dc_title @attr 4=2 "proceeding congress superconductivity"
 433       Z> scan @attr 1=dc_title abc
 434       ]]>
 435      </screen>
 436      or the proprietary
 437      extentions <literal>x-pquery</literal> and
 438      <literal>x-pScanClause</literal> to
 439      &sru;, and &srw;
 440      <screen>
 441       <![CDATA[
 442       http://localhost:9999/?version=1.1&operation=searchRetrieve&x-pquery=%40attr+1%3Ddc_creator+%40attr+4%3D6+%22the
 443       http://localhost:9999/?version=1.1&operation=scan&x-pScanClause=@attr+1=dc_date+@attr+4=2+a
 444       ]]>
 445      </screen>
 446      See <xref linkend="zebrasrv-sru"/> for more information on &sru;/&srw;
 447      configuration, and <xref linkend="gfs-config"/> or the &yaz;
 448      <ulink url="&url.yaz.cql;">&cql; section</ulink>
 449      for the details or the &yaz; frontend server.
 450     </para>
 451     <para>
 452      Notice that there are no <filename>*.abs</filename>,
 453      <filename>*.est</filename>, <filename>*.map</filename>, or other &grs1;
 454      filter configuration files involves in this process, and that the
 455      literal index names are used during search and retrieval.
 456     </para>
 457
 458    </section>
 459
 460    </section>
 461   </section>
 462
 463
 464   <section id="record-model-domxml-conf">
 465    <title>&dom; Record Model Configuration</title>
 466
 467
 468   <section id="record-model-domxml-index">
 469    <title>&dom; Indexing Configuration</title>
 470     <para>
 471      As mentioned above, there can be only one indexing
 472      stylesheet, and configuration of the indexing process is a synonym
 473      of writing an &xslt; stylesheet which produces &xml; output containing the
 474      magic elements discussed in
 475      <xref linkend="record-model-domxml-internal"/>.
 476      Obviously, there are million of different ways to accomplish this
 477      task, and some comments and code snippets are in order to lead
 478      our paduans on the right track to the  good side of the force.
 479     </para>
 480     <para>
 481      Stylesheets can be written in the <emphasis>pull</emphasis> or
 482      the <emphasis>push</emphasis> style: <emphasis>pull</emphasis>
 483      means that the output &xml; structure is taken as starting point of
 484      the internal structure of the &xslt; stylesheet, and portions of
 485      the input &xml; are <emphasis>pulled</emphasis> out and inserted
 486      into the right spots of the output &xml; structure. On the other
 487      side, <emphasis>push</emphasis> &xslt; stylesheets are recursavly
 488      calling their template definitions, a process which is commanded
 489      by the input &xml; structure, and avake to produce some output &xml;
 490      whenever some special conditions in the input styelsheets are
 491      met. The <emphasis>pull</emphasis> type is well-suited for input
 492      &xml; with strong and well-defined structure and semantcs, like the
 493      following &oai; indexing example, whereas the
 494      <emphasis>push</emphasis> type might be the only possible way to
 495      sort out deeply recursive input &xml; formats.
 496     </para>
 497     <para>
 498      A <emphasis>pull</emphasis> stylesheet example used to index
 499      &oai; harvested records could use some of the following template
 500      definitions:
 501      <screen>
 502       <![CDATA[
 503       <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 504        xmlns:z="http://indexdata.dk/zebra/xslt/1"
 505        xmlns:oai="http://www.openarchives.org/&oai;/2.0/"
 506        xmlns:oai_dc="http://www.openarchives.org/&oai;/2.0/oai_dc/"
 507        xmlns:dc="http://purl.org/dc/elements/1.1/"
 508        version="1.0">
 509
 510        <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 511
 512         <!-- disable all default text node output -->
 513         <xsl:template match="text()"/>
 514
 515          <!-- match on oai xml record root -->
 516          <xsl:template match="/">
 517           <z:record z:id="{normalize-space(oai:record/oai:header/oai:identifier)}"
 518            z:type="update">
 519            <!-- you might want to use z:rank="{some &xslt; function here}" -->
 520            <xsl:apply-templates/>
 521           </z:record>
 522          </xsl:template>
 523
 524          <!-- &oai; indexing templates -->
 525          <xsl:template match="oai:record/oai:header/oai:identifier">
 526           <z:index name="oai_identifier" type="0">
 527            <xsl:value-of select="."/>
 528           </z:index>
 529          </xsl:template>
 530
 531          <!-- etc, etc -->
 532
 533          <!-- DC specific indexing templates -->
 534          <xsl:template match="oai:record/oai:metadata/oai_dc:dc/dc:title">
 535           <z:index name="dc_title" type="w">
 536            <xsl:value-of select="."/>
 537           </z:index>
 538          </xsl:template>
 539
 540          <!-- etc, etc -->
 541
 542       </xsl:stylesheet>
 543       ]]>
 544      </screen>
 545     </para>
 546     <para>
 547      Notice also,
 548      that the names and types of the indexes can be defined in the
 549      indexing &xslt; stylesheet <emphasis>dynamically according to
 550      content in the original &xml; records</emphasis>, which has
 551      opportunities for great power and wizardery as well as grande
 552      disaster.
 553     </para>
 554     <para>
 555      The following excerpt of a <emphasis>push</emphasis> stylesheet
 556      <emphasis>might</emphasis>
 557      be a good idea according to your strict control of the &xml;
 558      input format (due to rigerours checking against well-defined and
 559      tight RelaxNG or &xml; Schema's, for example):
 560      <screen>
 561       <![CDATA[
 562       <xsl:template name="element-name-indexes">
 563        <z:index name="{name()}" type="w">
 564         <xsl:value-of select="'1'"/>
 565        </z:index>
 566       </xsl:template>
 567       ]]>
 568      </screen>
 569      This template creates indexes which have the name of the working
 570      node of any input  &xml; file, and assigns a '1' to the index.
 571      The example query
 572      <literal>find @attr 1=xyz 1</literal>
 573      finds all files which contain at least one
 574      <literal>xyz</literal> &xml; element. In case you can not control
 575      which element names the input files contain, you might ask for
 576      disaster and bad karma using this technique.
 577     </para>
 578     <para>
 579      One variation over the theme <emphasis>dynamically created
 580      indexes</emphasis> will definitely be unwise:
 581      <screen>
 582       <![CDATA[
 583       <!-- match on oai xml record root -->
 584       <xsl:template match="/">
 585        <z:record z:type="update">
 586
 587         <!-- create dynamic index name from input content -->
 588         <xsl:variable name="dynamic_content">
 589          <xsl:value-of select="oai:record/oai:header/oai:identifier"/>
 590         </xsl:variable>
 591
 592         <!-- create zillions of indexes with unknown names -->
 593         <z:index name="{$dynamic_content}" type="w">
 594          <xsl:value-of select="oai:record/oai:metadata/oai_dc:dc"/>
 595         </z:index>
 596        </z:record>
 597
 598       </xsl:template>
 599       ]]>
 600      </screen>
 601      Don't be tempted to cross
 602      the line to the dark side of the force, paduan; this leads
 603      to suffering and pain, and universal
 604      disentigration of your project schedule.
 605     </para>
 606   </section>
 607
 608   <section id="record-model-domxml-elementset">
 609    <title>&dom; Exchange Formats</title>
 610    <para>
 611      An exchange format can be anything which can be the outcome of an
 612      &xslt; transformation, as far as the stylesheet is registered in
 613      the main &dom; &xslt; filter configuration file, see
 614      <xref linkend="record-model-domxml-filter"/>.
 615      In principle anything that can be expressed in  &xml;, HTML, and
 616      TEXT can be the output of a <literal>schema</literal> or
 617     <literal>element set</literal> directive during search, as long as
 618      the information comes from the
 619      <emphasis>original input record &xml; &dom; tree</emphasis>
 620      (and not the transformed and <emphasis>indexed</emphasis> &xml;!!).
 621     </para>
 622     <para>
 623      In addition, internal administrative information from the &zebra;
 624      indexer can be accessed during record retrieval. The following
 625      example is a summary of the possibilities:
 626      <screen>
 627       <![CDATA[
 628       <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 629        xmlns:z="http://indexdata.dk/zebra/xslt/1"
 630        version="1.0">
 631
 632        <!-- register internal zebra parameters -->
 633        <xsl:param name="id" select="''"/>
 634        <xsl:param name="filename" select="''"/>
 635        <xsl:param name="score" select="''"/>
 636        <xsl:param name="schema" select="''"/>
 637
 638        <xsl:output indent="yes" method="xml" version="1.0" encoding="UTF-8"/>
 639
 640        <!-- use then for display of internal information -->
 641        <xsl:template match="/">
 642          <z:zebra>
 643            <id><xsl:value-of select="$id"/></id>
 644            <filename><xsl:value-of select="$filename"/></filename>
 645            <score><xsl:value-of select="$score"/></score>
 646            <schema><xsl:value-of select="$schema"/></schema>
 647          </z:zebra>
 648        </xsl:template>
 649
 650       </xsl:stylesheet>
 651       ]]>
 652      </screen>
 653     </para>
 654
 655   </section>
 656
 657   <section id="record-model-domxml-example">
 658    <title>&dom; Filter &oai; Indexing Example</title>
 659    <para>
 660      The sourcecode tarball contains a working &dom; filter example in
 661      the directory <filename>examples/dom-oai/</filename>, which
 662      should get you started.
 663     </para>
 664     <para>
 665      More example data can be harvested from any &oai; complient server,
 666      see details at the  &oai;
 667      <ulink url="http://www.openarchives.org/">
 668       http://www.openarchives.org/</ulink> web site, and the community
 669       links at
 670      <ulink url="http://www.openarchives.org/community/index.html">
 671       http://www.openarchives.org/community/index.html</ulink>.
 672      There is a  tutorial
 673      found at
 674      <ulink url="http://www.oaforum.org/tutorial/">
 675       http://www.oaforum.org/tutorial/</ulink>.
 676     </para>
 677    </section>
 678
 679   </section>
 680
 681
 682  </chapter>
 683
 684
 685 <!--
 686
 687 c)  Main "dom" &xslt; filter config file:
 688   cat db/filter_dom_conf.xml
 689
 690   <?xml version="1.0" encoding="UTF8"?>
 691   <schemaInfo>
 692     <schema name="dom" stylesheet="db/dom2dom.xsl" />
 693     <schema name="index" identifier="http://indexdata.dk/zebra/xslt/1"
 694             stylesheet="db/dom2index.xsl" />
 695     <schema name="dc" stylesheet="db/dom2dc.xsl" />
 696     <schema name="dc-short" stylesheet="db/dom2dc_short.xsl" />
 697     <schema name="snippet" snippet="25" stylesheet="db/dom2snippet.xsl" />
 698     <schema name="help" stylesheet="db/dom2help.xsl" />
 699     <split level="1"/>
 700   </schemaInfo>
 701
 702   the paths are relative to the directory where zebra.init is placed
 703   and is started up.
 704
 705   The split level decides where the SAX parser shall split the
 706   collections of records into individual records, which then are
 707   loaded into &dom;, and have the indexing &xslt; stylesheet applied.
 708
 709   The indexing stylesheet is found by it's identifier.
 710
 711   All the other stylesheets are for presentation after search.
 712
 713 - in data/ a short sample of harvested carnivorous plants
 714   ZEBRA_INDEX_DIRS=data/carnivor_20050118_2200_short-346.xml
 715
 716 - in root also one single data record - nice for testing the xslt
 717   stylesheets,
 718
 719   xsltproc db/dom2index.xsl carni*.xml
 720
 721   and so on.
 722
 723 - in db/ a cql2pqf.txt yaz-client config file
 724   which is also used in the yaz-server <ulink url="&url.cql;">&cql;</ulink>-to-&pqf; process
 725
 726    see: http://www.indexdata.com/yaz/doc/tools.tkl#tools.cql.map
 727
 728 - in db/ an indexing &xslt; stylesheet. This is a PULL-type XSLT thing,
 729   as it constructs the new &xml; structure by pulling data out of the
 730   respective elements/attributes of the old structure.
 731
 732   Notice the special zebra namespace, and the special elements in this
 733   namespace which indicate to the zebra indexer what to do.
 734
 735   <z:record id="67ht7" rank="675" type="update">
 736   indicates that a new record with given id and static rank has to be updated.
 737
 738   <z:index name="title" type="w">
 739    encloses all the text/&xml; which shall be indexed in the index named
 740    "title" and of index type "w" (see  file default.idx in your zebra
 741    installation)
 742
 743
 744    </para>
 745
 746    <para>
 747 -->
 748
 749
 750
 751
 752  <!-- Keep this comment at the end of the file
 753  Local variables:
 754  mode: sgml
 755  sgml-omittag:t
 756  sgml-shorttag:t
 757  sgml-minimize-attributes:nil
 758  sgml-always-quote-attributes:t
 759  sgml-indent-step:1
 760  sgml-indent-data:t
 761  sgml-parent-document: "zebra.xml"
 762  sgml-local-catalogs: nil
 763  sgml-namecase-general:t
 764  End:
 765  -->