Describe the asterisk substution for CQL to RPN mappings.

[yaz-moved-to-github.git] / doc / tools.xml

diff --git a/doc/tools.xml b/doc/tools.xml
index 9fb631d..9483a5c 100644 (file)
--- a/doc/tools.xml
+++ b/doc/tools.xml
@@ -1,4 +1,4 @@
-<!-- $Id: tools.xml,v 1.52 2006-10-09 21:02:40 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.56 2007-02-08 09:03:31 adam Exp $ -->
  <chapter id="tools"><title>Supporting Tools</title>
   
   <para>
@@ -129,11 +129,11 @@
     <literallayout>
      query ::= top-set query-struct.
 
-     top-set ::= &lsqb; '@attrset' string &rsqb;
+     top-set ::= [ '@attrset' string ]
 
      query-struct ::= attr-spec | simple | complex | '@term' term-type query
 
-     attr-spec ::= '@attr' &lsqb; string &rsqb; string query-struct
+     attr-spec ::= '@attr' [ string ] string query-struct
 
      complex ::= operator query-struct query-struct.
 
@@ -452,7 +452,7 @@
      <para>
       The CCL parser obeys the following grammar for the FIND argument.
       The syntax is annotated by in the lines prefixed by
-      <literal>&dash;&dash;</literal>.
+      <literal>--</literal>.
      </para>
 
      <screen>
@@ -890,7 +890,7 @@
       </table>
      </sect4>
     </sect3>
-    <sect3 id="ccl.apid">
+    <sect3 id="ccl.api">
      <title>CCL API</title>
      <para>
       All public definitions can be found in the header file
@@ -1263,6 +1263,13 @@ int cql_transform_FILE(cql_transform_t ct,
       <replaceable>value</replaceable> the attribute value.
      </para>
      <para>
+      The character <literal>*</literal> (asterisk) has special meaning
+      when used in the RPN pattern.
+      Each occurrence of <literal>*</literal> is substituted with the
+      CQL matching name (index, relation, qualifier etc).
+      This facility can be used to copy a CQL name verbatim to the RPN result.
+     </para>
+     <para>
       The following CQL patterns are recognized:
       <variablelist>
        <varlistentry><term>
@@ -1283,6 +1290,11 @@ int cql_transform_FILE(cql_transform_t ct,
           <literal>http://www.loc.gov/zing/cql/cql-indexes/v1.0/</literal>.
           If this pattern is not defined, the mapping will fail.
          </para>
+         <para>
+          The pattern, 
+          <literal>index.</literal><replaceable>set</replaceable><literal>.*</literal>
+          is used when no other index pattern is matched.
+        </para>
         </listitem>
        </varlistentry>
        <varlistentry><term>
@@ -1385,28 +1397,41 @@ int cql_transform_FILE(cql_transform_t ct,
          </para>
         </listitem>
        </varlistentry>
+
+       <varlistentry><term>
+         <literal>set</literal>
+        </term>
+        <listitem>
+         <para>
+          This specification defines a default CQL context set for index names.
+          The value on the right hand side is the URI for the set.
+         </para>
+        </listitem>
+       </varlistentry>
+
       </variablelist>
      </para>
-     <example id="example.cql.to.rpn.mapping"><title>CQL to RPN mapping file</title>
+     <example id="example.cql.to.rpn.mapping">
+      <title>CQL to RPN mapping file</title>
       <para>
        This simple file defines two context sets, three indexes and three
        relations, a position pattern and a default structure.
       </para>
       <programlisting><![CDATA[
-       set.cql    = http://www.loc.gov/zing/cql/context-sets/cql/v1.1/
-       set.dc     = http://www.loc.gov/zing/cql/dc-indexes/v1.0/
+       set.cql  = http://www.loc.gov/zing/cql/context-sets/cql/v1.1/
+       set.dc   = http://www.loc.gov/zing/cql/dc-indexes/v1.0/
 
        index.cql.serverChoice = 1=1016
        index.dc.title         = 1=4
        index.dc.subject       = 1=21
   
-       relation.<                 = 2=1
-       relation.eq                = 2=3
-       relation.scr               = 2=3
+       relation.<             = 2=1
+       relation.eq            = 2=3
+       relation.scr           = 2=3
 
-       position.any               = 3=3 6=1
+       position.any           = 3=3 6=1
 
-       structure.*                = 4=1
+       structure.*            = 4=1
 ]]>
       </programlisting>
       <para>
@@ -1441,6 +1466,49 @@ int cql_transform_FILE(cql_transform_t ct,
        </screen>
       </para>
      </example>
+     <example id="example.cql.to.rpn.string">
+      <title>CQL to RPN string attributes</title>
+      <para>
+       In this example we allow any index to be passed to RPN as
+       a use attribute.
+      </para>
+      <programlisting><![CDATA[
+       # Identifiers for prefixes used in this file. (index.*)
+       set.cql  = info:srw/cql-context-set/1/cql-v1.1
+       set.rpn  = http://bogus/rpn
+       set      = http://bogus/rpn
+
+       # The default index when none is specified by the query
+       index.cql.serverChoice     = 1=any
+
+       index.rpn.*                = 1=*
+       relation.eq                = 2=3
+       structure.*                = 4=1
+       position.any               = 3=3
+]]>
+      </programlisting>
+      <para>
+       The <literal>http://bogus/rpn</literal> context set is also the default
+       so we can make queries such as
+       <screen>
+        title = a
+       </screen>
+       which is converted to
+       <screen>
+        @attr 2=3 @attr 4=1 @attr 3=3 @attr 1=title "a"
+       </screen>
+      </para>
+     </example>
+     <example id="example.cql.to.rpn.bathprofile">
+      <title>CQL to RPN using Bath Profile</title>
+      <para>
+       The file <filename>etc/pqf.properties</filename> has mappings from
+       the Bath Profile and Dublin Core to RPN.
+       If YAZ is installed as a package it's usually located
+       in <filename>/usr/share/yaz/etc</filename> and part of the
+       development package, such as <literal>libyaz-dev</literal>.
+      </para>
+     </example>
     </sect3>
     <sect3 id="cql.xcql"><title>CQL to XCQL conversion</title>
      <para>
@@ -2030,7 +2098,7 @@ typedef struct oident
      </varlistentry>
 
      <varlistentry>
-      <term>YAZ_MARC_MARXML</term>
+      <term>YAZ_MARC_MARCXML</term>
       <listitem>
        <para>
        The resulting record is converted to MARCXML.