X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Ftools.xml;h=6c02fc5cc920f498ae323057c7315b9de0ef5060;hp=55dec3c248628cf8ac2f0b124afd347ed503e198;hb=b7dce0eae6656ccb499233e04f5a5bf90178c7cd;hpb=29c7ed2c90cd7aa5b69ec785c618b260f9525b1b diff --git a/doc/tools.xml b/doc/tools.xml index 55dec3c..6c02fc5 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -173,11 +173,15 @@ The @attr operator is followed by an attribute specification (attr-spec above). The specification consists - of optional an attribute set, an attribute type-value pair and - a sub query. The attribute type-value pair is packed in one string: - an attribute type, a dash, followed by an attribute value. + of an optional attribute set, an attribute type-value pair and + a sub-query. The attribute type-value pair is packed in one string: + an attribute type, an equals sign, and an attribute value, like this: + @attr 1=1003. The type is always an integer but the value may be either an integer or a string (if it doesn't start with a digit character). + A string attribute-value is encoded as a Type-1 ``complex'' + attribute with the list of values containing the single string + specified, and including no semantic indicators. @@ -297,101 +301,111 @@ PQF queries - Queries using simple terms. - - dylan - "bob dylan" - - - Boolean operators. - - @or "dylan" "zimmerman" - @and @or dylan zimmerman when - @and when @or dylan zimmerman - - - - Reference to result sets. - - @set Result-1 - @and @set seta setb - - - - Attributes for terms. - - @attr 1=4 computer - @attr 1=4 @attr 4=1 "self portrait" - @attrset exp1 @attr 1=1 CategoryList - @attr gils 1=2008 Copenhagen - @attr 1=/book/title computer - - - - Proximity. - - @prox 0 3 1 2 k 2 dylan zimmerman - - - Here the parameters 0, 3, 1, 2, k and 2 represent exclusion, - distance, ordered, relation, which-code and unit-code, in that - order. So: - - - exclusion = 0: the proximity condition must hold - - - distance = 3: the terms must be three units apart - - - ordered = 1: they must occur in the order they are specified - - - relation = 2: lessThanOrEqual (to the distance of 3 units) - - - which-code is ``known'', so the standard unit-codes are used - - - unit-code = 2: word. - - - So the whole proximity query means that the words - dylan and zimmerman must - both occur in the record, in that order, differing in position - by three or fewer words (i.e. with two or fewer words between - them.) The query would find ``Bob Dylan, aka. Robert - Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman'' - since the distance in this case is four. - - - - Specifying term type. - - @term string "a UTF-8 string, maybe?" - - - Mixed queries - - @or @and bob dylan @set Result-1 - - @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming" - - @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109 + PQF queries using simple terms + + + dylan + "bob dylan" + + + + PQF boolean operators + + + @or "dylan" "zimmerman" + @and @or dylan zimmerman when + @and when @or dylan zimmerman + + + + PQF references to result sets + + + @set Result-1 + @and @set seta setb + + + + Attributes for terms + + + @attr 1=4 computer + @attr 1=4 @attr 4=1 "self portrait" + @attrset exp1 @attr 1=1 CategoryList + @attr gils 1=2008 Copenhagen + @attr 1=/book/title computer + + + + PQF Proximity queries + + + @prox 0 3 1 2 k 2 dylan zimmerman + + + Here the parameters 0, 3, 1, 2, k and 2 represent exclusion, + distance, ordered, relation, which-code and unit-code, in that + order. So: + + + exclusion = 0: the proximity condition must hold + + + distance = 3: the terms must be three units apart + + + ordered = 1: they must occur in the order they are specified + + + relation = 2: lessThanOrEqual (to the distance of 3 units) + + + which-code is ``known'', so the standard unit-codes are used + + + unit-code = 2: word. + + + So the whole proximity query means that the words + dylan and zimmerman must + both occur in the record, in that order, differing in position + by three or fewer words (i.e. with two or fewer words between + them.) The query would find ``Bob Dylan, aka. Robert + Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman'' + since the distance in this case is four. + + + + PQF specification of search term + + + @term string "a UTF-8 string, maybe?" + + + + PQF mixed queries + + + @or @and bob dylan @set Result-1 + + @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming" + + @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109 - + - The last of these examples is a spatial search: in - the GILS attribute set, - access point - 2038 indicates West Bounding Coordinate and - 2030 indicates East Bounding Coordinate, - so the query is for areas extending from -114 degrees - to no more than -109 degrees. + access point + 2038 indicates West Bounding Coordinate and + 2030 indicates East Bounding Coordinate, + so the query is for areas extending from -114 degrees + to no more than -109 degrees. - - + + + CCL @@ -407,8 +421,7 @@ - The EUROPAGATE - research project working under the Libraries programme + The EUROPAGATE research project working under the Libraries programme of the European Commission's DG XIII has, amongst other useful tools, implemented a general-purpose CCL parser which produces an output structure that can be trivially converted to the internal RPN @@ -1195,9 +1208,9 @@ int cql_transform_error(cql_transform_t ct, char **addinfop); error-code and sets the string-pointer at *addinfop to point to a string containing additional information about the error that occurred: for - example, if the error code is 15 (``Illegal or unsupported index + example, if the error code is 15 (``Illegal or unsupported context set''), the additional information is the name of the requested - index set that was not recognised. + context set that was not recognised. The SRW error-codes may be translated into brief human-readable @@ -1253,26 +1266,37 @@ int cql_transform_FILE(cql_transform_t ct, The following CQL patterns are recognized: - qualifier.set.name + index.set.name - This pattern is invoked when a CQL qualifier, such as + This pattern is invoked when a CQL index, such as dc.title is converted. set - and name is the index set and qualifier + and name are the context set and index name respectively. Typically, the RPN specifies an equivalent use attribute. - For terms not bound by a qualifier the pattern - qualifier.srw.serverChoice is used. - Here, the prefix srw is defined as - http://www.loc.gov/zing/cql/srw-indexes/v1.0/. + For terms not bound by an index the pattern + index.cql.serverChoice is used. + Here, the prefix cql is defined as + http://www.loc.gov/zing/cql/cql-indexes/v1.0/. If this pattern is not defined, the mapping will fail. + qualifier.set.name + (DEPRECATED) + + + + For backwards compatibility, this is recognised as a synonym of + index.set.name + + + + relation.relation @@ -1354,10 +1378,10 @@ int cql_transform_FILE(cql_transform_t ct, - This specification defines a CQL index set for a given prefix. + This specification defines a CQL context set for a given prefix. The value on the right hand side is the URI for the set - not RPN. All prefixes used in - qualifier patterns must be defined this way. + index patterns must be defined this way. @@ -1365,16 +1389,16 @@ int cql_transform_FILE(cql_transform_t ct, CQL to RPN mapping file - This simple file defines two index sets, three qualifiers and three + This simple file defines two context sets, three indexes and three relations, a position pattern and a default structure. @attr 1=1016 @attr 2=3 @attr 4=1 @attr 3=3 @attr 6=1 "computer" - by rules qualifier.srw.serverChoice, + by rules index.cql.serverChoice, relation.scr, structure.*, position.any. @@ -1744,7 +1768,7 @@ typedef struct oident release the associated memory again. For the structures describing the Z39.50 PDUs and related structures, it is convenient to use the memory-management system of the &odr; subsystem (see - Using ODR). However, in some circumstances + ). However, in some circumstances where you might otherwise benefit from using a simple nibble memory management system, it may be impractical to use odr_malloc() and odr_reset().