-<!-- $Id: tools.xml,v 1.48 2006-04-24 12:41:00 marc 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
- <ulink url="&url.srw;">SRW</ulink> protocol.
+ <ulink url="&url.sru;">SRU</ulink> protocol.
In many ways CQL has a similar syntax to CCL.
The objective of CQL is different. Where CCL aims to be
an end-user language, CQL is <emphasis>the</emphasis> protocol
- query language for SRW.
+ query language for SRU.
</para>
<tip>
<para>
<listitem>
<para>
The parser converts a valid CQL query to PQF, thus providing a
- way to use CQL for both SRW/SRU servers and Z39.50 targets at the
+ way to use CQL for both SRU servers and Z39.50 targets at the
same time.
</para>
</listitem>
The parser converts CQL to
<ulink url="&url.xcql;">XCQL</ulink>.
XCQL is an XML representation of CQL.
- XCQL is part of the SRW specification. However, since SRU
+ XCQL is part of the SRU specification. However, since SRU
supports CQL only, we don't expect XCQL to be widely used.
Furthermore, CQL has the advantage over XCQL that it is
easy to read.
</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
capabilities (combinations of supported attributes).
- In addition, the CQL and SRW operates on index prefixes
+ In addition, the CQL and SRU operates on index prefixes
(URI or strings), whereas the RPN uses Object Identifiers
for attribute sets.
</para>
</para>
<para>
If conversion failed, <function>cql_transform_buf</function>
- returns a non-zero SRW error code; otherwise zero is returned
+ returns a non-zero SRU error code; otherwise zero is returned
(conversion successful). The meanings of the numeric error
- codes are listed in the SRW specifications at
+ codes are listed in the SRU specifications at
<ulink url="&url.sru.diagnostics.list;"/>
</para>
<para>
context set that was not recognised.
</para>
<para>
- The SRW error-codes may be translated into brief human-readable
+ The SRU error-codes may be translated into brief human-readable
error messages using
<synopsis>
const char *cql_strerror(int code);
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
</chapter>
- <!-- Keep this Emacs mode comment at the end of the file
-Local variables:
-mode: nxml
-End:
--->
-
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "yaz.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->
projects / yaz-moved-to-github.git / blobdiff