-<!-- $Id: tools.xml,v 1.50 2006-06-13 16:01:51 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.54 2006-10-31 09:15:00 mike Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
<sect3 id="pqf-examples"><title>PQF queries</title>
- <example><title>PQF queries using simple terms</title>
+ <example id="example.pqf.simple.terms">
+ <title>PQF queries using simple terms</title>
<para>
<screen>
dylan
</screen>
</para>
</example>
- <example><title>PQF boolean operators</title>
+ <example id="pqf.example.pqf.boolean.operators">
+ <title>PQF boolean operators</title>
<para>
<screen>
@or "dylan" "zimmerman"
</screen>
</para>
</example>
- <example><title>PQF references to result sets</title>
+ <example id="example.pqf.result.sets">
+ <title>PQF references to result sets</title>
<para>
<screen>
@set Result-1
</screen>
</para>
</example>
- <example><title>Attributes for terms</title>
+ <example id="example.pqf.attributes">
+ <title>Attributes for terms</title>
<para>
<screen>
@attr 1=4 computer
</screen>
</para>
</example>
- <example><title>PQF Proximity queries</title>
+ <example id="example.pqf.proximity">
+ <title>PQF Proximity queries</title>
<para>
<screen>
@prox 0 3 1 2 k 2 dylan zimmerman
</para></note>
</para>
</example>
- <example><title>PQF specification of search term</title>
+ <example id="example.pqf.search.term.type">
+ <title>PQF specification of search term type</title>
<para>
<screen>
@term string "a UTF-8 string, maybe?"
</screen>
</para>
</example>
- <example><title>PQF mixed queries</title>
+ <example id="example.pqf.mixed.queries">
+ <title>PQF mixed queries</title>
<para>
<screen>
@or @and bob dylan @set Result-1
license, it is included as a supplement to &yaz;.
</para>
- <sect3><title>CCL Syntax</title>
+ <sect3 id="ccl.syntax">
+ <title>CCL Syntax</title>
<para>
The CCL parser obeys the following grammar for the FIND argument.
</screen>
- <example><title>CCL queries</title>
+ <example id="example.ccl.queries">
+ <title>CCL queries</title>
<para>
The following queries are all valid:
</para>
</example>
</sect3>
- <sect3><title>CCL Qualifiers</title>
+ <sect3 id="ccl.qualifiers">
+ <title>CCL Qualifiers</title>
<para>
Qualifiers are used to direct the search to a particular searchable
lines in a CCL profile: qualifier specification,
qualifier alias, comments and directives.
</para>
- <sect4><title id="qualifier-specification">Qualifier specification</title>
+ <sect4 id="ccl.qualifier.specification">
+ <title>Qualifier specification</title>
<para>
A qualifier specification is of the form:
</para>
or <literal>c</literal> for completeness.
The attributes for the special qualifier name <literal>term</literal>
are used when no CCL qualifier is given in a query.
- <table><title>Common Bib-1 attributes</title>
+ <table id="ccl.common.bib1.attributes">
+ <title>Common Bib-1 attributes</title>
<tgroup cols="2">
<colspec colwidth="2*" colname="type"></colspec>
<colspec colwidth="9*" colname="description"></colspec>
which are used in combination with certain types.
The special combinations are:
- <table><title>Special attribute combos</title>
+ <table id="ccl.special.attribute.combos">
+ <title>Special attribute combos</title>
<tgroup cols="2">
<colspec colwidth="2*" colname="name"></colspec>
<colspec colwidth="9*" colname="description"></colspec>
</tgroup>
</table>
</para>
- <example><title>CCL profile</title>
+ <example id="example.ccl.profile"><title>CCL profile</title>
<para>
Consider the following definition:
</para>
</para>
</example>
</sect4>
- <sect4><title>Qualifier alias</title>
+ <sect4 id="ccl.qualifier.alias">
+ <title>Qualifier alias</title>
<para>
A qualifier alias is of the form:
</para>
</para>
</sect4>
- <sect4><title>Comments</title>
+ <sect4 id="ccl.comments">
+ <title>Comments</title>
<para>
Lines with white space or lines that begin with
character <literal>#</literal> are treated as comments.
</para>
</sect4>
- <sect4><title>Directives</title>
+ <sect4 id="ccl.directives">
+ <title>Directives</title>
<para>
Directive specifications takes the form
</para>
<para><literal>@</literal><replaceable>directive</replaceable> <replaceable>value</replaceable>
</para>
- <table><title>CCL directives</title>
+ <table id="ccl.directives.table">
+ <title>CCL directives</title>
<tgroup cols="3">
<colspec colwidth="2*" colname="name"></colspec>
<colspec colwidth="8*" colname="description"></colspec>
</table>
</sect4>
</sect3>
- <sect3><title>CCL API</title>
+ <sect3 id="ccl.api">
+ <title>CCL API</title>
<para>
All public definitions can be found in the header file
<filename>ccl.h</filename>. A profile identifier is of type
</para>
</sect3>
</sect2>
- <sect2 id="tools.cql"><title>CQL</title>
+ <sect2 id="cql"><title>CQL</title>
<para>
<ulink url="&url.cql;">CQL</ulink>
- Common Query Language - was defined for the
</listitem>
</itemizedlist>
</para>
- <sect3 id="tools.cql.parsing"><title>CQL parsing</title>
+ <sect3 id="cql.parsing"><title>CQL parsing</title>
<para>
A CQL parser is represented by the <literal>CQL_parser</literal>
handle. Its contents should be considered &yaz; internal (private).
</para>
</sect3>
- <sect3 id="tools.cql.tree"><title>CQL tree</title>
+ <sect3 id="cql.tree"><title>CQL tree</title>
<para>
The the query string is valid, the CQL parser
generates a tree representing the structure of the
</para>
</sect3>
- <sect3 id="tools.cql.pqf"><title>CQL to PQF conversion</title>
+ <sect3 id="cql.to.pqf"><title>CQL to PQF conversion</title>
<para>
Conversion to PQF (and Z39.50 RPN) is tricky by the fact
that the resulting RPN depends on the Z39.50 target
open <literal>FILE</literal>.
</para>
</sect3>
- <sect3 id="tools.cql.map">
+ <sect3 id="cql.to.rpn">
<title>Specification of CQL to RPN mappings</title>
<para>
The file supplied to functions
</varlistentry>
</variablelist>
</para>
- <example><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.
</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="tools.cql.xcql"><title>CQL to XCQL conversion</title>
+ <sect3 id="cql.xcql"><title>CQL to XCQL conversion</title>
<para>
Conversion from CQL to XCQL is trivial and does not
require a mapping to be defined.
</sect1>
- <sect1 id="tools.marc"><title>MARC</title>
+ <sect1 id="marc"><title>MARC</title>
<para>
YAZ provides a fast utility that decodes MARC records and
</varlistentry>
<varlistentry>
- <term>YAZ_MARC_MARXML</term>
+ <term>YAZ_MARC_MARCXML</term>
<listitem>
<para>
The resulting record is converted to MARCXML.
stores the resulting record in a WRBUF handle (WRBUF is a simple string
type).
</para>
- <example>
+ <example id="example.marc.display">
<title>Display of MARC record</title>
<para>
The followint program snippet illustrates how the MARC API may