From: Sebastian Hammer Date: Fri, 30 Mar 2007 01:07:37 +0000 (+0000) Subject: Added documentation for the settings system. Still needs examples X-Git-Tag: PAZPAR2.1.0.0~383 X-Git-Url: http://jsfdemo.indexdata.com/cgi-bin?a=commitdiff_plain;h=5e78ae75781eb20fd3359b57f352e8aa4b8bf8ae;p=pazpar2-moved-to-github.git Added documentation for the settings system. Still needs examples --- diff --git a/doc/pazpar2_conf.xml b/doc/pazpar2_conf.xml index fac262d..2a4c2fe 100644 --- a/doc/pazpar2_conf.xml +++ b/doc/pazpar2_conf.xml @@ -8,7 +8,7 @@ %common; ]> - + Pazpar2 @@ -374,7 +374,7 @@ Pazpar2 features a cunning scheme by which you can associate various kinds of attributes, or settings with search targets. This is done - through XML files, and each file can associate one or more settings + through XML files; each file can associate one or more settings with one or more targets. The file format is generic in nature, designed to support a wide range of application requirements. The settings can be purely technical things, like, how to perform a title @@ -393,8 +393,146 @@ SETTINGS FILE FORMAT + Each file contains a root element named <settings>. It may + contain one or more <set> elements. The settings and set + elements may contain the following attributes. Attributes in set + overrides those in the setting root element. Each set node must + specify (directly, or inherited from the parent node) at least a + target, name, and value. + + + + target + + + This specifies the search target to which this setting should be + applied. Targets are identified by their Z39.50 URL, generally + including the host, port, and database name, (e.g. + bagel.indexdata.com:210/marc). Two wildcard forms are accepted: + * (asterisk) matches all known targets; + bagel.indexdata.com:210/* matches all known databases on the given + host. + + + A precedence system determines what happens if there are + overlapping values for the same setting name for the same + target. A setting for a specific target name overrides a + setting whch specifies target using a wildcard. This makes it + easy to set defaults for all targets, and then override them + for specific targets or hosts. If there are + multiple overlapping settings with the same name and target + value, the 'precedence' attribute determines what happens. + + + + + user + + + This specifies the user ID to which this setting applies. A + given setting may have values for any number of users, or it + may have a 'default' value which is applied when no user is + specified, or when no user-specific value is available. + + + + + name + + + The name of the setting. This can be anything you like. + However, pazpar2 reserves a number of setting names for + specific purposes, all starting with 'pz:', and it is a good + idea to avoid that prefix if you make up your own setting + names. See below for a list of reserved variables. + + + + + value + + + The value of the setting. Generally, this can be anything you + want -- however, some of the reserved settings may expect + specific kinds of values. + + + + + precedence + + + This should be an integer. If not provided, the default value + is 0. If two (or more) settings have the same content for + target and name, the precedence value determines the outcome. + If both settings have the same precedence value, they are both + applied to the target(s). If one has a higher value, then the + value of that setting is applied, and the other one is ignored. + + + + + + + By setting defaults for user, target, name, or value in the root + settings node, you can use the settings files in many different + ways. For instance, you can use a single file to set defaults for + many different settings, like search fields, retrieval syntaxes, + etc. You can have one file per server, which groups settings for + that server or target. You could also have one file which associates + a number of targets with a given setting, for instance, to associate + many databases with a given category or class that makes sense + within your application. + + + + RESERVED SETTING NAMES + + The following setting names are reserved by pazpar2 to control the + behavior of the client function. + + + + + pz:cclmap:xxx + + + This establishes a CCL field definition or other setting, for + the purpose of mapping end-user queries. XXX is the field or + setting name, and the value of the setting provides parameters + (e.g. parameters to send to the server, etc.). Please consult + the YAZ manual for a full overview of the many capabilities of + the powerful and flexible CCL parser. + + + Note that it is easy to etablish a set of default parameters, + and then override them individually for a given target. + + + + + pz:syntax + + + This specifies the record syntax to use when requesting + records from a given server. + + + + + pz:elements + + + The element set name to be used when retrieving records from a + server. + + + + + +