+<?xml version="1.0" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
"http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
[
<!ENTITY % idcommon SYSTEM "common/common.ent">
%idcommon;
]>
-<!-- $Id: pazpar2_conf.xml,v 1.27 2007-06-22 13:18:23 adam Exp $ -->
<refentry id="pazpar2_conf">
<refentryinfo>
<productname>Pazpar2</productname>
<refsect2 id="config-server"><title>server</title>
<para>
- This section governs overall behavior of the client. The data
- elements are described below.
+ This section governs overall behavior of the server. The data
+ elements are described below. From Pazpar2 version 1.2 this is
+ a repeatable element.
</para>
<variablelist> <!-- level 1 -->
<varlistentry>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>relevance / sort / mergekey</term>
+ <listitem>
+ <para>
+ Specifies character set normalization for relevancy / sorting
+ and the mergekey - for the server. These definitions serves as
+ default for services that don't have these given. For the meaning
+ of these settings refer to the "relevance" element inside service.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
- <term>icu_chain</term>
+ <term>settings</term>
<listitem>
<para>
- Definition of ICU tokenization and normalization rules
- are used if ICU support is compiled in. The 'id'
- attribute is currently not used, and the 'locale'
- attribute must be set to one of the locale strings
- defined in ICU. The child elements listed below can be
- in any order, except the 'index' element which logically
- belongs to the end of the list. The stated tokenization,
- normalization and charmapping instructions are performed
- in order from top to bottom.
+ Specifies target settings for the server.. These settings serves
+ as default for all services which don't have these given.
+ The settings element requires one attribute 'src' which specifies
+ a settings file or a directory . If a directory is given all
+ files with suffix <filename>.xml</filename> is read from this
+ directory. Refer to
+ <xref linkend="target_settings"/> for more information.
</para>
- <variablelist> <!-- Level 2 -->
- <varlistentry><term>casemap</term>
- <listitem>
- <para>
- The attribute 'rule' defines the direction of the
- per-character casemapping, allowed values are "l"
- (lower), "u" (upper), "t" (title).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>normalize</term>
- <listitem>
- <para>
- Normalization and transformation of tokens follows
- the rules defined in the 'rule' attribute. For
- possible values we refer to the extensive ICU
- documentation found at the
- <ulink url="&url.icu.transform;">ICU
- transformation</ulink> home page. Set filtering
- principles are explained at the
- <ulink url="&url.icu.unicode.set;">ICU set and
- filtering</ulink> page.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>tokenize</term>
- <listitem>
- <para>
- Tokenization is the only rule in the ICU chain
- which splits one token into multiple tokens. The
- 'rule' attribute may have the following values:
- "s" (sentence), "l" (line-break), "w" (word), and
- "c" (character), the later probably not being
- very useful in a pruning Pazpar2 installation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>index</term>
- <listitem>
- <para>
- Finally the 'index' element instruction - without
- any 'rule' attribute - is used to store the tokens
- after chain processing in the relevance ranking
- unit of Pazpar2. It will always be the last
- instruction in the chain.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
</listitem>
</varlistentry>
extraction of data from the internal representation, primarily
through the 'metadata' sub-element.
</para>
-
+ <para>
+ Pazpar2 version 1.2 and later allows multiple service elements.
+ Multiple services must be given a unique ID by specifying
+ attribute <literal>id</literal>.
+ A single service may be unnamed (service ID omitted). The
+ service ID is referred to in the
+ <link linkend="command-init"><literal>init</literal></link> webservice
+ command's <literal>service</literal> parameter.
+ </para>
+
<variablelist> <!-- Level 2 -->
<varlistentry><term>metadata</term>
<listitem>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry><term>mergekey</term>
+ <listitem>
+ <para>
+ If set to <literal>yes</literal>, the value of this
+ metadata element is appended to the resulting mergekey.
+ By default metadata is not part of a mergekey.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry><term>setting</term>
+ <listitem>
+ <para>
+ This attribute allows you to make use of static database
+ settings in the processing of records. Three possible values
+ are allowed. 'no' is the default and doesn't do anything.
+ 'postproc' copies the value of a setting with the same name
+ into the output of the normalization stylesheet(s). 'parameter'
+ makes the value of a setting with the same name available
+ as a parameter to the normalization stylesheet, so you
+ can further process the value inside of the stylesheet, or use
+ the value to decide how to deal with other data values.
+ </para>
+ <para>
+ The purpose of using settings in this way can either be to
+ control the behavior of normalization stylesheet in a database-
+ dependent way, or to easily make database-dependent values
+ available to display-logic in your user interface, without having
+ to implement complicated interactions between the user interface
+ and your configuration system.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist> <!-- attributes to metadata -->
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>relevance</term>
+ <listitem>
+ <para>
+ Specifies ICU tokenization and transformation rules
+ for tokens that are used in Pazpar2's relevance ranking.
+ The 'id' attribute is currently not used, and the 'locale'
+ attribute must be set to one of the locale strings
+ defined in ICU. The child elements listed below can be
+ in any order, except the 'index' element which logically
+ belongs to the end of the list. The stated tokenization,
+ transformation and charmapping instructions are performed
+ in order from top to bottom.
+ </para>
+ <variablelist> <!-- Level 2 -->
+ <varlistentry><term>casemap</term>
+ <listitem>
+ <para>
+ The attribute 'rule' defines the direction of the
+ per-character casemapping, allowed values are "l"
+ (lower), "u" (upper), "t" (title).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>transform</term>
+ <listitem>
+ <para>
+ Normalization and transformation of tokens follows
+ the rules defined in the 'rule' attribute. For
+ possible values we refer to the extensive ICU
+ documentation found at the
+ <ulink url="&url.icu.transform;">ICU
+ transformation</ulink> home page. Set filtering
+ principles are explained at the
+ <ulink url="&url.icu.unicode.set;">ICU set and
+ filtering</ulink> page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry><term>tokenize</term>
+ <listitem>
+ <para>
+ Tokenization is the only rule in the ICU chain
+ which splits one token into multiple tokens. The
+ 'rule' attribute may have the following values:
+ "s" (sentence), "l" (line-break), "w" (word), and
+ "c" (character), the later probably not being
+ very useful in a pruning Pazpar2 installation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ From Pazpar2 version 1.1 the ICU wrapper from YAZ is used.
+ Refer to the <ulink url="&url.yaz.yaz-icu;">yaz-icu</ulink>
+ utility for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>sort</term>
+ <listitem>
+ <para>
+ Specifies ICU tokenization and transformation rules
+ for tokens that are used in Pazpar2's sorting. The contents
+ is similar to that of <literal>relevance</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mergekey</term>
+ <listitem>
+ <para>
+ Specifies ICU tokenization and transformation rules
+ for tokens that are used in Pazpar2's mergekey. The contents
+ is similar to that of <literal>relevance</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>settings</term>
+ <listitem>
+ <para>
+ Specifies target settings for this service. Refer to
+ <xref linkend="target_settings"/>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>timeout</term>
+ <listitem>
+ <para>
+ Specifies timeout parameters for this service.
+ The <literal>timeout</literal>
+ element supports the following attributes:
+ <literal>session</literal>, <literal>z3950_operation</literal>,
+ <literal>z3950_session</literal> which specifies
+ 'session timeout', 'Z39.50 operation timeout',
+ 'Z39.50 session timeout' respectively. The Z39.50 operation
+ timeout is the time Pazpar2 will wait for an active Z39.50/SRU
+ operation before it gives up (times out). The Z39.50 session
+ time out is the time Pazpar2 will keep the session alive for
+ an idle session (no operation).
+ </para>
+ <para>
+ The following is recommended but not required:
+ z3950_operation (30) < session (60) < z3950_session (180) .
+ The default values are given in parantheses.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist> <!-- Data elements in service directive -->
</listitem>
</varlistentry>
+
</variablelist> <!-- Data elements in server directive -->
</refsect2>
-
+
</refsect1>
<refsect1><title>EXAMPLE</title>
<para>Below is a working example configuration:
- <screen><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
-
-<server>
- <listen port="9004"/>
- <proxy host="us1.indexdata.com" myurl="us1.indexdata.com"/>
-
- <!-- optional ICU ranking configuration example -->
- <!--
- <icu_chain id="el:word" locale="el">
- <normalize rule="[:Control:] Any-Remove"/>
- <tokenize rule="l"/>
- <normalize rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
- <casemap rule="l"/>
- <index/>
- </icu_chain>
- -->
-
- <service>
- <metadata name="title" brief="yes" sortkey="skiparticle" merge="longest" rank="6"/>
- <metadata name="isbn" merge="unique"/>
- <metadata name="date" brief="yes" sortkey="numeric" type="year" merge="range"
- termlist="yes"/>
- <metadata name="author" brief="yes" termlist="yes" merge="longest" rank="2"/>
- <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
- <metadata name="url" merge="unique"/>
- </service>
-</server>
-
-</pazpar2>
-]]></screen>
+ <screen><![CDATA[
+ <?xml version="1.0" encoding="UTF-8"?>
+ <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
+
+ <server>
+ <listen port="9004"/>
+ <service>
+ <metadata name="title" brief="yes" sortkey="skiparticle"
+ merge="longest" rank="6"/>
+ <metadata name="isbn" merge="unique"/>
+ <metadata name="date" brief="yes" sortkey="numeric"
+ type="year" merge="range" termlist="yes"/>
+ <metadata name="author" brief="yes" termlist="yes"
+ merge="longest" rank="2"/>
+ <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
+ <metadata name="url" merge="unique"/>
+ <relevance>
+ <icu_chain id="relevance" locale="el">
+ <transform rule="[:Control:] Any-Remove"/>
+ <tokenize rule="l"/>
+ <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
+ <casemap rule="l"/>
+ </icu_chain>
+ </relevance>
+ <settings src="mysettings"/>
+ <timeout session="60"/>
+ <service>
+ </server>
+ </pazpar2>
+ ]]></screen>
</para>
</refsect1>
-
+
+ <refsect1 id="config-include"><title>INCLUDE FACILITY</title>
+ <para>
+ The XML configuration may be partitioned into multiple files by using
+ the <literal>include</literal> element which takes a single attribute,
+ <literal>src</literal>. The of the <literal>src</literal> attribute is
+ regular Shell like glob-pattern. For example,
+ <screen><![CDATA[
+ <include src="/etc/pazpar2/conf.d/*.xml"/>
+ ]]></screen>
+ </para>
+ <para>
+ The include facility requires Pazpar2 version 1.2.
+ </para>
+ </refsect1>
+
<refsect1 id="target_settings"><title>TARGET SETTINGS</title>
<para>
Pazpar2 features a cunning scheme by which you can associate various
pairs with groups of targets -- for instance, if you would like to
place all commercial full-text bases in one group for selection
purposes, or you would like to control what targets are accessible
- to users by default.
+ to users by default. Per-database settings values can even be used
+ to drive sorting, facet/termlist generation, or end-user interface display
+ logic.
</para>
<para>
environment, where different end-users may need to be represented to
some search targets in different ways. This, again, can be managed
using an external database or other lookup mechanism. Setting overrides
- can be performed either using the 'init' or the 'settings' webservice
+ can be performed either using the
+ <link linkend="command-init">init</link> or the
+ <link linkend="command-settings">settings</link> webservice
command.
</para>
<para>
Finally, as an extreme case of this, the webservice client can
- introduce entirely new targets, on the fly, as part of the init or
- settings command. This is useful if you desire to manage information
+ introduce entirely new targets, on the fly, as part of the
+ <link linkend="command-init">init</link> or
+ <link linkend="command-settings">settings</link> command.
+ This is useful if you desire to manage information
about your search targets in a separate application such as a database.
You do not need any static settings file whatsoever to run Pazpar2 -- as
long as the webservice client is prepared to supply the necessary
<settings target="*">
<!-- This file introduces default settings for pazpar2 -->
- <!-- $Id: pazpar2_conf.xml,v 1.27 2007-06-22 13:18:23 adam Exp $ -->
<!-- mapping for unqualified search -->
<set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
<!-- Retrieval settings -->
<set name="pz:requestsyntax" value="marc21"/>
- <!-- <set name="pz:elements" value="F"/> NOT YET IMPLEMENTED -->
+ <set name="pz:elements" value="F"/>
+
+ <!-- Query encoding -->
+ <set name="pz:queryencoding" value="iso-8859-1"/>
<!-- Result normalization settings -->
<listitem>
<para>
The element set name to be used when retrieving records from a
- server (not yet implemented).
+ server.
</para>
</listitem>
</varlistentry>
For iso2709, can also specify a native character set, e.g. "iso2709;latin-1".
If no character set is provided, MARC-8 is assumed.
</para>
+ <para>
+ If pz:nativesyntax is not specified, pazpar2 will attempt to determine
+ the value based on the response from the server.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pz:queryencoding</term>
+ <listitem>
+ <para>
+ The encoding of the search terms that a target accepts. Most
+ targets do not honor UTF-8 in which case this needs to be specified.
+ Each term in a query will be converted if this setting is given.
+ </para>
</listitem>
</varlistentry>
+
<varlistentry>
<term>pz:xslt</term>
<listitem>
<listitem>
<para>
Controls the maximum number of records to be retrieved from a
- server. The default is 100 (not yet implemented).
+ server. The default is 100.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>pz:apdulog</term>
+ <listitem>
+ <para>
+ If the 'pz:apdulog' setting is defined and has other value than 0,
+ then Z39.50 APDUs are written to the log.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pz:sru</term>
+ <listitem>
+ <para>
+ This setting enables SRU/SRW support. It has three possible settings.
+ 'get', enables SRU access through GET requests. 'post' enables SRU/POST
+ support, less commonly supported, but useful if very large requests are
+ to be submitted. 'srw' enables the SRW variation of the protocol.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pz:sru_version</term>
+ <listitem>
+ <para>
+ This allows SRU version to be specified. If unset Pazpar2
+ will the default of YAZ (currently 1.2). Should be set
+ to 1.1 or 1.2.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pz:pqf_prefix</term>
+ <listitem>
+ <para>
+ Allows you to specify an arbitrary PQF query language substring. The provided
+ string is prefixed the user's query after it has been normalized to PQF
+ internally in pazpar2. This allows you to attach complex 'filters' to
+ queries for a gien target, sometimes necessary to select sub-catalogs
+ in union catalog systems, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pz:sort</term>
+ <listitem>
+ <para>
+ Specifies sort criteria to be applied to the result set. Only works for targets
+ which support the sort service.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
</refsect1>
+ <refsect1><title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pazpar2</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>yaz-icu</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ <citerefentry>
+ <refentrytitle>pazpar2_protocol</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
projects / pazpar2-moved-to-github.git / blobdiff