From a31f9b2d25006c89ae7e9fb5870c0d222ee88a3a Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 8 Apr 2002 13:50:12 +0000 Subject: [PATCH] docbook xml manual --- configure.in | 55 +- doc/Makefile.am | 26 +- doc/administration.xml | 3430 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/indexdata.xml | 63 + doc/installation.xml | 79 ++ doc/introduction.xml | 293 +++++ doc/license.xml | 54 + doc/xml.dcl | 179 +++ doc/zebra.xml.in | 43 + doc/zebrahtml.dsl.in | 26 + doc/zebraprint.dsl.in | 21 + 11 files changed, 4253 insertions(+), 16 deletions(-) create mode 100644 doc/administration.xml create mode 100644 doc/indexdata.xml create mode 100644 doc/installation.xml create mode 100644 doc/introduction.xml create mode 100644 doc/license.xml create mode 100644 doc/xml.dcl create mode 100644 doc/zebra.xml.in create mode 100644 doc/zebrahtml.dsl.in create mode 100644 doc/zebraprint.dsl.in diff --git a/configure.in b/configure.in index 25cc0a4..3007b3c 100644 --- a/configure.in +++ b/configure.in @@ -1,5 +1,5 @@ dnl Zebra, Index Data Aps, 1994-2002 -dnl $Id: configure.in,v 1.34 2002-04-05 19:45:20 adam Exp $ +dnl $Id: configure.in,v 1.35 2002-04-08 13:50:12 adam Exp $ dnl AC_INIT(include/zebraver.h) AC_MSG_CHECKING(for package) @@ -16,7 +16,6 @@ else fi AM_CONDITIONAL(ISZMBOL,test $PACKAGE = zmbol) dnl ------ Substitutions -AC_SUBST(DEFS) AC_SUBST(TCL_INCLUDE) AC_SUBST(TCL_LIB) AC_SUBST(PROGPREFIX) @@ -26,7 +25,54 @@ AC_PROG_CC AC_PROG_CPP AC_PROG_INSTALL AC_PROG_RANLIB - +dnl +dnl ----- DOCBOOK DTD +AC_SUBST(DTD_DIR) +AC_ARG_WITH(dtd, [ --with-dtd[=DIR] Use docbookx.dtd in DIR], +[ + if test -f "$withval/docbookx.dtd"; then + DTD_DIR=$withval + fi +],[ + AC_MSG_CHECKING(for docbookx.dtd) + for d in /usr/share/sgml/docbook/dtd/xml/4.1.2 \ + /usr/share/sgml/docbook/xml-dtd-4.1.2 \ + /usr/share/sgml/docbook/dtd/xml/4.0 \ + /usr/lib/sgml/dtd/docbook-xml + do + if test -f $d/docbookx.dtd; then + AC_MSG_RESULT($d) + DTD_DIR=$d + break + fi + done + if test -z "$DTD_DIR"; then + AC_MSG_RESULT(Not found) + fi +]) +AC_SUBST(DSSSL_DIR) +AC_ARG_WITH(dsssl,[ --with-dsssl[=DIR] Use DSSSL in DIR/{html,print}/docbook.dsl], +[ + if test -f "$withval/html/docbook.dsl"; then + DSSSL_DIR=$withval + fi +],[ + AC_MSG_CHECKING(for docbook.dsl) + for d in /usr/share/sgml/docbook/stylesheet/dsssl/modular \ + /usr/share/sgml/docbook/dsssl-stylesheets-1.64 \ + /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh + do + if test -f $d/html/docbook.dsl; then + AC_MSG_RESULT($d) + DSSSL_DIR=$d + break + fi + done + if test -z "$DSSSL_DIR"; then + AC_MSG_RESULT(Not found) + fi +]) +dnl YAZ_INIT(threads) dnl dnl ------ Look for Tcl @@ -145,5 +191,8 @@ AC_OUTPUT([ include/Makefile tab/Makefile doc/Makefile + doc/zebra.xml + doc/zebrahtml.dsl + doc/zebraprint.dsl test/Makefile test/gils/Makefile test/usmarc/Makefile test/api/Makefile ]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 8496264..c10e249 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,23 +1,23 @@ -## $Id: Makefile.am,v 1.3 2000-07-06 11:40:37 adam Exp $ +## $Id: Makefile.am,v 1.4 2002-04-08 13:50:13 adam Exp $ docdir=$(pkgdatadir)/doc -doc_DATA = zebra.sgml gils.sgml zebra.txt zebra.ps zebra.html \ - zebra-1.html zebra-2.html zebra-3.html zebra-4.html zebra-5.html \ - zebra-6.html zebra-7.html zebra-8.html zebra-9.html +doc_data = zebra.pdf zebra.html +SUPPORTFILES = zebrahtml.dsl.in zebraprint.dsl.in xml.dsl + EXTRA_DIST = zebra.sgml gils.sgml zebra.txt zebra.ps zebra.html \ zebra-1.html zebra-2.html zebra-3.html zebra-4.html zebra-5.html \ - zebra-6.html zebra-7.html zebra-8.html zebra-9.html - -zebra.txt: zebra.sgml - sgml2txt -f zebra.sgml - -zebra.ps: zebra.sgml - sgml2latex -o ps -p a4 zebra.sgml + zebra-6.html zebra-7.html zebra-8.html zebra-9.html \ + zebra.xml.in $(SUPPORTFILES) -zebra.html: zebra.sgml - sgml2html zebra.sgml +zebra.pdf: zebra.xml + jade -E14 -d zebraprint.dsl -t tex xml.dcl zebra.xml + pdfjadetex zebra.tex + pdfjadetex zebra.tex + pdfjadetex zebra.tex +zebra.html: zebra.xml + jade -E14 -d zebrahtml.dsl -t sgml xml.dcl zebra.xml gils.txt: gils.sgml sgml2txt -f gils.sgml diff --git a/doc/administration.xml b/doc/administration.xml new file mode 100644 index 0000000..ccb156f --- /dev/null +++ b/doc/administration.xml @@ -0,0 +1,3430 @@ + +Quick Start + + +In this section, we will test the system by indexing a small set of sample +GILS records that are included with the software distribution. Go to the +test/gils subdirectory of the distribution archive. There you will +find a configuration +file named zebra.cfg with the following contents: + + +# Where are the YAZ tables located. +profilePath: ../../../yaz/tab ../../tab + +# Files that describe the attribute sets supported. +attset: bib1.att +attset: gils.att + + + + + +Now, edit the file and set profilePath to the path of the +YAZ profile tables (sub directory tab of the YAZ distribution +archive). + + + +The 48 test records are located in the sub directory records. +To index these, type: + + +$ ../../index/zebraidx -t grs.sgml update records + + + + + +In the command above the option -t specified the record +type — in this case grs.sgml. The word update followed +by a directory root updates all files below that directory node. + + + +If your indexing command was successful, you are now ready to +fire up a server. To start a server on port 2100, type: + + +$ ../../index/zebrasrv tcp:@:2100 + + + + + +The Zebra index that you have just created has a single database +named Default. The database contains records structured according to +the GILS profile, and the server will +return records in either either USMARC, GRS-1, or SUTRS depending +on what your client asks +for. + + + +To test the server, you can use any Z39.50 client (1992 or later). For +instance, you can use the demo client that comes with YAZ: Just cd to +the client subdirectory of the YAZ distribution and type: + + + + + +$ client tcp:localhost:2100 + + + + + +When the client has connected, you can type: + + + + + +Z> find surficial +Z> show 1 + + + + + +The default retrieval syntax for the client is USMARC. To try other +formats for the same record, try: + + + + + +Z>format sutrs +Z>show 1 +Z>format grs-1 +Z>show 1 +Z>elements B +Z>show 1 + + + + + +NOTE: You may notice that more fields are returned when your +client requests SUTRS or GRS-1 records. When retrieving GILS records, +this is normal - not all of the GILS data elements have mappings in +the USMARC record format. + + + +If you've made it this far, there's a good chance that +you've got through the compilation OK. + + + + + +Administrating Zebra + + +Unlike many simpler retrieval systems, Zebra supports safe, incremental +updates to an existing index. + + + +Normally, when Zebra modifies the index it reads a number of records +that you specify. +Depending on your specifications and on the contents of each record +one the following events take place for each record: + + + +Insert + + +The record is indexed as if it never occurred +before. Either the Zebra system doesn't know how to identify the record or +Zebra can identify the record but didn't find it to be already indexed. + + + + +Modify + + +The record has already been indexed. In this case +either the contents of the record or the location (file) of the record +indicates that it has been indexed before. + + + + +Delete + + +The record is deleted from the index. As in the +update-case it must be able to identify the record. + + + + + + + +Please note that in both the modify- and delete- case the Zebra +indexer must be able to generate a unique key that identifies the record in +question (more on this below). + + + +To administrate the Zebra retrieval system, you run the +zebraidx program. This program supports a number of options +which are preceded by a minus, and a few commands (not preceded by +minus). + + + +Both the Zebra administrative tool and the Z39.50 server share a +set of index files and a global configuration file. The +name of the configuration file defaults to zebra.cfg. +The configuration file includes specifications on how to index +various kinds of records and where the other configuration files +are located. zebrasrv and zebraidx must +be run in the directory where the configuration file lives unless you +indicate the location of the configuration file by option +-c. + + + +Record Types + + +Indexing is a per-record process, in which either insert/modify/delete +will occur. Before a record is indexed search keys are extracted from +whatever might be the layout the original record (sgml,html,text, etc..). +The Zebra system currently supports two fundamantal types of records: +structured and simple text. +To specify a particular extraction process, use either the +command line option -t or specify a +recordType setting in the configuration file. + + + + + +The Zebra Configuration File + + +The Zebra configuration file, read by zebraidx and +zebrasrv defaults to zebra.cfg unless specified +by -c option. + + + +You can edit the configuration file with a normal text editor. +parameter names and values are seperated by colons in the file. Lines +starting with a hash sign (#) are treated as comments. + + + +If you manage different sets of records that share common +characteristics, you can organize the configuration settings for each +type into "groups". +When zebraidx is run and you wish to address a given group +you specify the group name with the -g option. In this case +settings that have the group name as their prefix will be used +by zebraidx. If no -g option is specified, the settings +with no prefix are used. + + + +In the configuration file, the group name is placed before the option +name itself, separated by a dot (.). For instance, to set the record type +for group public to grs.sgml (the SGML-like format for structured +records) you would write: + + + + + +public.recordType: grs.sgml + + + + + +To set the default value of the record type to text write: + + + + + +recordType: text + + + + + +The available configuration settings are summarized below. They will be +explained further in the following sections. + + + + + + +group.recordType[.name] + + +Specifies how records with the file extension name should +be handled by the indexer. This option may also be specified +as a command line option (-t). Note that if you do not +specify a name, the setting applies to all files. In general, +the record type specifier consists of the elements (each +element separated by dot), fundamental-type, +file-read-type and arguments. Currently, two +fundamental types exist, text and grs. + + + + +group.recordId + + +Specifies how the records are to be identified when updated. See +section . + + + + +group.database + + +Specifies the Z39.50 database name. + + + + +group.storeKeys + + +Specifies whether key information should be saved for a given +group of records. If you plan to update/delete this type of +records later this should be specified as 1; otherwise it +should be 0 (default), to save register space. See section +. + + + + +group.storeData + + +Specifies whether the records should be stored internally +in the Zebra system files. If you want to maintain the raw records yourself, +this option should be false (0). If you want Zebra to take care of the records +for you, it should be true(1). + + + + +register + + +Specifies the location of the various register files that Zebra uses +to represent your databases. See section +. + + + + +shadow + + +Enables the safe update facility of Zebra, and tells the system +where to place the required, temporary files. See section +. + + + + +lockDir + + +Directory in which various lock files are stored. + + + + +keyTmpDir + + +Directory in which temporary files used during zebraidx' update +phase are stored. + + + + +setTmpDir + + +Specifies the directory that the server uses for temporary result sets. +If not specified /tmp will be used. + + + + +profilePath + + +Specifies the location of profile specification files. + + + + +attset + + +Specifies the filename(s) of attribute set files for use in +searching. At least the Bib-1 set should be loaded (bib1.att). +The profilePath setting is used to look for the specified files. +See section + + + + +memMax + + +Specifies size of internal memory to use for the zebraidx program. The +amount is given in megabytes - default is 4 (4 MB). + + + + + + + + + +Locating Records + + +The default behaviour of the Zebra system is to reference the +records from their original location, i.e. where they were found when you +ran zebraidx. That is, when a client wishes to retrieve a record +following a search operation, the files are accessed from the place +where you originally put them - if you remove the files (without +running zebraidx again, the client will receive a diagnostic +message. + + + +If your input files are not permanent - for example if you retrieve +your records from an outside source, or if they were temporarily +mounted on a CD-ROM drive, +you may want Zebra to make an internal copy of them. To do this, +you specify 1 (true) in the storeData setting. When +the Z39.50 server retrieves the records they will be read from the +internal file structures of the system. + + + + + +Indexing with no Record IDs (Simple Indexing) + + +If you have a set of records that are not expected to change over time +you may can build your database without record IDs. +This indexing method uses less space than the other methods and +is simple to use. + + + +To use this method, you simply omit the recordId entry +for the group of files that you index. To add a set of records you use +zebraidx with the update command. The +update command will always add all of the records that it +encounters to the index - whether they have already been indexed or +not. If the set of indexed files change, you should delete all of the +index files, and build a new index from scratch. + + + +Consider a system in which you have a group of text files called +simple. That group of records should belong to a Z39.50 database +called textbase. The following zebra.cfg file will suffice: + + + + + +profilePath: /usr/local/yaz +attset: bib1.att +simple.recordType: text +simple.database: textbase + + + + + +Since the existing records in an index can not be addressed by their +IDs, it is impossible to delete or modify records when using this method. + + + + + +Indexing with File Record IDs + + +If you have a set of files that regularly change over time: Old files +are deleted, new ones are added, or existing files are modified, you +can benefit from using the file ID indexing methodology. Examples +of this type of database might include an index of WWW resources, or a +USENET news spool area. Briefly speaking, the file key methodology +uses the directory paths of the individual records as a unique +identifier for each record. To perform indexing of a directory with +file keys, again, you specify the top-level directory after the +update command. The command will recursively traverse the +directories and compare each one with whatever have been indexed before in +that same directory. If a file is new (not in the previous version of +the directory) it is inserted into the registers; if a file was +already indexed and it has been modified since the last update, +the index is also modified; if a file has been removed since the last +visit, it is deleted from the index. + + + +The resulting system is easy to administrate. To delete a record you +simply have to delete the corresponding file (say, with the rm +command). And to add records you create new files (or directories with +files). For your changes to take effect in the register you must run +zebraidx update with the same directory root again. This mode +of operation requires more disk space than simpler indexing methods, +but it makes it easier for you to keep the index in sync with a +frequently changing set of data. If you combine this system with the +safe update facility (see below), you never have to take your +server offline for maintenance or register updating purposes. + + + +To enable indexing with pathname IDs, you must specify file as +the value of recordId in the configuration file. In addition, +you should set storeKeys to 1, since the Zebra +indexer must save additional information about the contents of each record +in order to modify the indices correctly at a later time. + + + +For example, to update records of group esdd located below +/data1/records/ you should type: + + +$ zebraidx -g esdd update /data1/records + + + + + +The corresponding configuration file includes: + + +esdd.recordId: file +esdd.recordType: grs.sgml +esdd.storeKeys: 1 + + + + + +Important note: You cannot start out with a group of records with simple +indexing (no record IDs as in the previous section) and then later +enable file record Ids. Zebra must know from the first time that you +index the group that +the files should be indexed with file record IDs. + + + +You cannot explicitly delete records when using this method (using the +delete command to zebraidx. Instead +you have to delete the files from the file system (or move them to a +different location) +and then run zebraidx with the update command. + + + + + +Indexing with General Record IDs + + +When using this method you construct an (almost) arbritrary, internal +record key based on the contents of the record itself and other system +information. If you have a group of records that explicitly associates +an ID with each record, this method is convenient. For example, the +record format may contain a title or a ID-number - unique within the group. +In either case you specify the Z39.50 attribute set and use-attribute +location in which this information is stored, and the system looks at +that field to determine the identity of the record. + + + +As before, the record ID is defined by the recordId setting +in the configuration file. The value of the record ID specification +consists of one or more tokens separated by whitespace. The resulting +ID is +represented in the index by concatenating the tokens and separating them by +ASCII value (1). + + + +There are three kinds of tokens: + + + +Internal record info + + +The token refers to a key that is +extracted from the record. The syntax of this token is +( set , use ), where set is the +attribute set name use is the name or value of the attribute. + + + + +System variable + + +The system variables are preceded by + + +$ + + and immediately followed by the system variable name, which +may one of + + + +group + + +Group name. + + + + +database + + +Current database specified. + + + + +type + + +Record type. + + + + + + + + +Constant string + + +A string used as part of the ID — surrounded +by single- or double quotes. + + + + + + + +For instance, the sample GILS records that come with the Zebra +distribution contain a unique ID in the data tagged Control-Identifier. +The data is mapped to the Bib-1 use attribute Identifier-standard +(code 1007). To use this field as a record id, specify +(bib1,Identifier-standard) as the value of the +recordId in the configuration file. +If you have other record types that uses the same field for a +different purpose, you might add the record type +(or group or database name) to the record id of the gils +records as well, to prevent matches with other types of records. +In this case the recordId might be set like this: + + +gils.recordId: $type (bib1,Identifier-standard) + + + + + +(see section +for details of how the mapping between elements of your records and +searchable attributes is established). + + + +As for the file record ID case described in the previous section, +updating your system is simply a matter of running zebraidx +with the update command. However, the update with general +keys is considerably slower than with file record IDs, since all files +visited must be (re)read to discover their IDs. + + + +As you might expect, when using the general record IDs +method, you can only add or modify existing records with the update +command. If you wish to delete records, you must use the, +delete command, with a directory as a parameter. +This will remove all records that match the files below that root +directory. + + + + + +Register Location + + +Normally, the index files that form dictionaries, inverted +files, record info, etc., are stored in the directory where you run +zebraidx. If you wish to store these, possibly large, files +somewhere else, you must add the register entry to the +zebra.cfg file. Furthermore, the Zebra system allows its file +structures to +span multiple file systems, which is useful for managing very large +databases. + + + +The value of the register setting is a sequence of tokens. +Each token takes the form: + + +dir:size. + + +The dir specifies a directory in which index files will be +stored and the size specifies the maximum size of all +files in that directory. The Zebra indexer system fills each directory +in the order specified and use the next specified directories as needed. +The size is an integer followed by a qualifier +code, M for megabytes, k for kilobytes. + + + +For instance, if you have allocated two disks for your register, and +the first disk is mounted +on /d1 and has 200 Mb of free space and the +second, mounted on /d2 has 300 Mb, you could +put this entry in your configuration file: + + +register: /d1:200M /d2:300M + + + + + +Note that Zebra does not verify that the amount of space specified is +actually available on the directory (file system) specified - it is +your responsibility to ensure that enough space is available, and that +other applications do not attempt to use the free space. In a large production system, +it is recommended that you allocate one or more filesystem exclusively +to the Zebra register files. + + + + + +Safe Updating - Using Shadow Registers + + +Description + + +The Zebra server supports updating of the index structures. That is, +you can add, modify, or remove records from databases managed by Zebra +without rebuilding the entire index. Since this process involves +modifying structured files with various references between blocks of +data in the files, the update process is inherently sensitive to +system crashes, or to process interruptions: Anything but a +successfully completed update process will leave the register files in +an unknown state, and you will essentially have no recourse but to +re-index everything, or to restore the register files from a backup +medium. Further, while the update process is active, users cannot be +allowed to access the system, as the contents of the register files +may change unpredictably. + + + +You can solve these problems by enabling the shadow register system in +Zebra. During the updating procedure, zebraidx will temporarily +write changes to the involved files in a set of "shadow +files", without modifying the files that are accessed by the +active server processes. If the update procedure is interrupted by a +system crash or a signal, you simply repeat the procedure - the +register files have not been changed or damaged, and the partially +written shadow files are automatically deleted before the new updating +procedure commences. + + + +At the end of the updating procedure (or in a separate operation, if +you so desire), the system enters a "commit mode". First, +any active server processes are forced to access those blocks that +have been changed from the shadow files rather than from the main +register files; the unmodified blocks are still accessed at their +normal location (the shadow files are not a complete copy of the +register files - they only contain those parts that have actually been +modified). If the commit process is interrupted at any point during the +commit process, the server processes will continue to access the +shadow files until you can repeat the commit procedure and complete +the writing of data to the main register files. You can perform +multiple update operations to the registers before you commit the +changes to the system files, or you can execute the commit operation +at the end of each update operation. When the commit phase has +completed successfully, any running server processes are instructed to +switch their operations to the new, operational register, and the +temporary shadow files are deleted. + + + + + +How to Use Shadow Register Files + + +The first step is to allocate space on your system for the shadow +files. You do this by adding a shadow entry to the zebra.cfg +file. The syntax of the shadow entry is exactly the same as for +the register entry (see section ). The location of the shadow area should be +different from the location of the main register area (if you +have specified one - remember that if you provide no register +setting, the default register area is the +working directory of the server and indexing processes). + + + +The following excerpt from a zebra.cfg file shows one example of +a setup that configures both the main register location and the shadow +file area. Note that two directories or partitions have been set aside +for the shadow file area. You can specify any number of directories +for each of the file areas, but remember that there should be no +overlaps between the directories used for the main registers and the +shadow files, respectively. + + + + + +register: /d1:500M + +shadow: /scratch1:100M /scratch2:200M + + + + + +When shadow files are enabled, an extra command is available at the +zebraidx command line. In order to make changes to the system +take effect for the users, you'll have to submit a +"commit" command after a (sequence of) update +operation(s). You can ask the indexer to commit the changes +immediately after the update operation: + + + + + +$ zebraidx update /d1/records update /d2/more-records commit + + + + + +Or you can execute multiple updates before committing the changes: + + + + + +$ zebraidx -g books update /d1/records update /d2/more-records +$ zebraidx -g fun update /d3/fun-records +$ zebraidx commit + + + + + +If one of the update operations above had been interrupted, the commit +operation on the last line would fail: zebraidx will not let you +commit changes that would destroy the running register. You'll have to +rerun all of the update operations since your last commit operation, +before you can commit the new changes. + + + +Similarly, if the commit operation fails, zebraidx will not let +you start a new update operation before you have successfully repeated +the commit operation. The server processes will keep accessing the +shadow files rather than the (possibly damaged) blocks of the main +register files until the commit operation has successfully completed. + + + +You should be aware that update operations may take slightly longer +when the shadow register system is enabled, since more file access +operations are involved. Further, while the disk space required for +the shadow register data is modest for a small update operation, you +may prefer to disable the system if you are adding a very large number +of records to an already very large database (we use the terms +large and modest very loosely here, since every +application will have a different perception of size). To update the system +without the use of the the shadow files, simply run zebraidx with +the -n option (note that you do not have to execute the +commit command of zebraidx when you temporarily disable the +use of the shadow registers in this fashion. Note also that, just as +when the shadow registers are not enabled, server processes will be +barred from accessing the main register while the update procedure +takes place. + + + + + + + + + +Running the Maintenance Interface (zebraidx) + + +The following is a complete reference to the command line interface to +the zebraidx application. + + + +Syntax + + +$ zebraidx [options] command [directory] ... + + +Options + + + +-t type + + +Update all files as type. Currently, the +types supported are text and grs.subtype. If no +subtype is provided for the GRS (General Record Structure) type, +the canonical input format is assumed (see section ). Generally, it +is probably advisable to specify the record types in the +zebra.cfg file +(see section ), to avoid +confusion at subsequent updates. + + + + +-c config-file + + +Read the configuration file +config-file instead of zebra.cfg. + + + + +-g group + + +Update the files according to the group +settings for group (see section +). + + + + +-d database + + +The records located should be associated +with the database name database for access through the Z39.50 +server. + + + + +-m mbytes + + +Use mbytes of megabytes before flushing +keys to background storage. This setting affects performance when +updating large databases. + + + + +-n + + +Disable the use of shadow registers for this operation +(see section ). + + + + +-s + + +Show analysis of the indexing process. The maintenance +program works in a read-only mode and doesn't change the state +of the index. This options is very useful when you wish to test a +new profile. + + + + +-V + + +Show Zebra version. + + + + +-v level + + +Set the log level to level. level +should be one of none, debug, and all. + + + + + + + +Commands + + + +Update directory + + +Update the register with the files +contained in directory. If no directory is provided, a list of +files is read from stdin. +See section . + + + + +Delete directory + + +Remove the records corresponding to +the files found under directory from the register. + + + + +Commit + + +Write the changes resulting from the last update +commands to the register. This command is only available if the use of +shadow register files is enabled (see section +). + + + + + + + + + +The Z39.50 Server + + +Running the Z39.50 Server (zebrasrv) + + +Syntax + + +zebrasrv [options] [listener-address ...] + + + + + +Options + + + +-a APDU file + + +Specify a file for dumping PDUs (for diagnostic purposes). +The special name "-" sends output to stderr. + + + + +-c config-file + + +Read configuration information from config-file. The default configuration is ./zebra.cfg. + + + + +-S + + +Don't fork on connection requests. This can be useful for +symbolic-level debugging. The server can only accept a single +connection in this mode. + + + + +-s + + +Use the SR protocol. + + + + +-z + + +Use the Z39.50 protocol (default). These two options complement +eachother. You can use both multiple times on the same command +line, between listener-specifications (see below). This way, you +can set up the server to listen for connections in both protocols +concurrently, on different local ports. + + + + +-l logfile + + +Specify an output file for the diagnostic +messages. The default is to write this information to stderr. + + + + +-v log-level + + +The log level. Use a comma-separated list of members of the set +{fatal,debug,warn,log,all,none}. + + + + +-u username + + +Set user ID. Sets the real UID of the server process to that of the +given username. It's useful if you aren't comfortable with having the +server run as root, but you need to start it as such to bind a +privileged port. + + + + +-w working-directory + + +Change working directory. + + + + +-i + + +Run under the Internet superserver, inetd. Make +sure you use the logfile option -l in conjunction with this +mode and specify the -l option before any other options. + + + + +-t timeout + + +Set the idle session timeout (default 60 minutes). + + + + +-k kilobytes + + +Set the (approximate) maximum size of +present response messages. Default is 1024 Kb (1 Mb). + + + + + + + +A listener-address consists of a transport mode followed by a +colon (:) followed by a listener address. The transport mode is +either osi or tcp. + + + +For TCP, an address has the form + + + + + +hostname | IP-number [: portnumber] + + + + + +The port number defaults to 210 (standard Z39.50 port). + + + +For OSI (only available if the server is compiled with XTI/mOSI +support enabled), the address form is + + + + + +[t-selector /] hostname | IP-number [: portnumber] + + + + + +The transport selector is given as a string of hex digits (with an even +number of digits). The default port number is 102 (RFC1006 port). + + + +Examples + + + + + +tcp:dranet.dra.com + +osi:0402/dbserver.osiworld.com:3000 + + + + + +In both cases, the special hostname "@" is mapped to +the address INADDR_ANY, which causes the server to listen on any local +interface. To start the server listening on the registered ports for +Z39.50 and SR over OSI/RFC1006, and to drop root privileges once the +ports are bound, execute the server like this (from a root shell): + + + + + +zebrasrv -u daemon tcp:@ -s osi:@ + + + + + +You can replace daemon with another user, eg. your own account, or +a dedicated IR server account. + + + +The default behavior for zebrasrv is to establish a single TCP/IP +listener, for the Z39.50 protocol, on port 9999. + + + + + +Z39.50 Protocol Support and Behavior + + +Initialization + + +During initialization, the server will negotiate to version 3 of the +Z39.50 protocol, and the option bits for Search, Present, Scan, +NamedResultSets, and concurrentOperations will be set, if requested by +the client. The maximum PDU size is negotiated down to a maximum of +1Mb by default. + + + + + +Search + + +The supported query type are 1 and 101. All operators are currently +supported with the restriction that only proximity units of type "word" are +supported for the proximity operator. +Queries can be arbitrarily complex. +Named result sets are supported, and result sets can be used as operands +without limitations. +Searches may span multiple databases. + + + +The server has full support for piggy-backed present requests (see +also the following section). + + + +Use attributes are interpreted according to the attribute sets which +have been loaded in the zebra.cfg file, and are matched against +specific fields as specified in the .abs file which describes the +profile of the records which have been loaded. If no Use +attribute is provided, a default of Bib-1 Any is assumed. + + + +If a Structure attribute of Phrase is used in conjunction with a +Completeness attribute of Complete (Sub)field, the term is +matched against the contents of the phrase (long word) register, if one +exists for the given Use attribute. +A phrase register is created for those fields in the .abs +file that contains a p-specifier. + + + +If Structure=Phrase is used in conjunction with +Incomplete Field - the default value for Completeness, the +search is directed against the normal word registers, but if the term +contains multiple words, the term will only match if all of the words +are found immediately adjacent, and in the given order. +The word search is performed on those fields that are indexed as +type w in the .abs file. + + + +If the Structure attribute is Word List, +Free-form Text, or Document Text, the term is treated as a +natural-language, relevance-ranked query. +This search type uses the word register, i.e. those fields +that are indexed as type w in the .abs file. + + + +If the Structure attribute is Numeric String the +term is treated as an integer. The search is performed on those +fields that are indexed as type n in the .abs file. + + + +If the Structure attribute is URx the +term is treated as a URX (URL) entity. The search is performed on those +fields that are indexed as type u in the .abs file. + + + +If the Structure attribute is Local Number the +term is treated as native Zebra Record Identifier. + + + +If the Relation attribute is Equals (default), the term is +matched in a normal fashion (modulo truncation and processing of +individual words, if required). If Relation is Less Than, +Less Than or Equal, Greater than, or Greater than or +Equal, the term is assumed to be numerical, and a standard regular +expression is constructed to match the given expression. If +Relation is Relevance, the standard natural-language query +processor is invoked. + + + +For the Truncation attribute, No Truncation is the default. +Left Truncation is not supported. Process # is supported, as +is Regxp-1. Regxp-2 enables the fault-tolerant (fuzzy) +search. As a default, a single error (deletion, insertion, +replacement) is accepted when terms are matched against the register +contents. + + + +Regular expressions + + +Each term in a query is interpreted as a regular expression if +the truncation value is either Regxp-1 (102) or Regxp-2 (103). +Both query types follow the same syntax with the operands: + + + +x + + +Matches the character x. + + + + +. + + +Matches any character. + + + + +[..] + + +Matches the set of characters specified; +such as [abc] or [a-c]. + + + + +and the operators: + + + +x* + + +Matches x zero or more times. Priority: high. + + + + +x+ + + +Matches x one or more times. Priority: high. + + + + +x? + + +Matches x once or twice. Priority: high. + + + + +xy + + +Matches x, then y. Priority: medium. + + + + +x|y + + +Matches either x or y. Priority: low. + + + + +The order of evaluation may be changed by using parentheses. + + + +If the first character of the Regxp-2 query is a plus character +(+) it marks the beginning of a section with non-standard +specifiers. The next plus character marks the end of the section. +Currently Zebra only supports one specifier, the error tolerance, +which consists one digit. + + + +Since the plus operator is normally a suffix operator the addition to +the query syntax doesn't violate the syntax for standard regular +expressions. + + + + + +Query examples + + +Phrase search for information retrieval in the title-register: + + + @attr 1=4 "information retrieval" + + + + + +Ranked search for the same thing: + + + @attr 1=4 @attr 2=102 "Information retrieval" + + + + + +Phrase search with a regular expression: + + + @attr 1=4 @attr 5=102 "informat.* retrieval" + + + + + +Ranked search with a regular expression: + + + @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval" + + + + + +In the GILS schema (gils.abs), the west-bounding-coordinate is +indexed as type n, and is therefore searched by specifying +structure=Numeric String. +To match all those records with west-bounding-coordinate greater +than -114 we use the following query: + + + @attr 4=109 @attr 2=5 @attr gils 1=2038 -114 + + + + + + + + + +Present + + +The present facility is supported in a standard fashion. The requested +record syntax is matched against the ones supported by the profile of +each record retrieved. If no record syntax is given, SUTRS is the +default. The requested element set name, again, is matched against any +provided by the relevant record profiles. + + + + + +Scan + + +The attribute combinations provided with the termListAndStartPoint are +processed in the same way as operands in a query (see above). +Currently, only the term and the globalOccurrences are returned with +the termInfo structure. + + + + + +Sort + + +Z39.50 specifies three diffent types of sort criterias. +Of these Zebra supports the attribute specification type in which +case the use attribute specifies the "Sort register". +Sort registers are created for those fields that are of type "sort" in +the default.idx file. +The corresponding character mapping file in default.idx specifies the +ordinal of each character used in the actual sort. + + + +Z39.50 allows the client to specify sorting on one or more input +result sets and one output result set. +Zebra supports sorting on one result set only which may or may not +be the same as the output result set. + + + + + +Close + + +If a Close PDU is received, the server will respond with a Close PDU +with reason=FINISHED, no matter which protocol version was negotiated +during initialization. If the protocol version is 3 or more, the +server will generate a Close PDU under certain circumstances, +including a session timeout (60 minutes by default), and certain kinds of +protocol errors. Once a Close PDU has been sent, the protocol +association is considered broken, and the transport connection will be +closed immediately upon receipt of further data, or following a short +timeout. + + + + + + + + + +The Record Model + + +The Zebra system is designed to support a wide range of data management +applications. The system can be configured to handle virtually any +kind of structured data. Each record in the system is associated with +a record schema which lends context to the data elements of the +record. Any number of record schema can coexist in the system. +Although it may be wise to use only a single schema within +one database, the system poses no such restrictions. + + + +The record model described in this chapter applies to the fundamental, +structured +record type grs as introduced in +section . + + + +Records pass through three different states during processing in the +system. + + + + + + + + +When records are accessed by the system, they are represented +in their local, or native format. This might be SGML or HTML files, +News or Mail archives, MARC records. If the system doesn't already +know how to read the type of data you need to store, you can set up an +input filter by preparing conversion rules based on regular +expressions and possibly augmented by a flexible scripting language (Tcl). The input filter +produces as output an internal representation: + + + + + + +When records are processed by the system, they are represented +in a tree-structure, constructed by tagged data elements hanging off a +root node. The tagged elements may contain data or yet more tagged +elements in a recursive structure. The system performs various +actions on this tree structure (indexing, element selection, schema +mapping, etc.), + + + + + + +Before transmitting records to the client, they are first +converted from the internal structure to a form suitable for exchange +over the network - according to the Z39.50 standard. + + + + + + + + +Local Representation + + +As mentioned earlier, Zebra places few restrictions on the type of +data that you can index and manage. Generally, whatever the form of +the data, it is parsed by an input filter specific to that format, and +turned into an internal structure that Zebra knows how to handle. This +process takes place whenever the record is accessed - for indexing and +retrieval. + + + +The RecordType parameter in the zebra.cfg file, or the -t +option to the indexer tells Zebra how to process input records. Two +basic types of processing are available - raw text and structured +data. Raw text is just that, and it is selected by providing the +argument text to Zebra. Structured records are all handled +internally using the basic mechanisms described in the subsequent +sections. Zebra can read structured records in many different formats. +How this is done is governed by additional parameters after the +"grs" keyboard, separated by "." characters. + + + +Three basic subtypes to the grs type are currently available: + + + + + + +grs.sgml + + +This is the canonical input format — +described below. It is a simple SGML-like syntax. + + + + +grs.regx.filter + + +This enables a user-supplied input +filter. The mechanisms of these filters are described below. + + + + +grs.marc.abstract syntax + + +This allows Zebra to read +records in the ISO2709 (MARC) encoding standard. In this case, the +last paramemeter abstract syntax names the .abs file (see below) +which describes the specific MARC structure of the input record as +well as the indexing rules. + + + + + + + +Canonical Input Format + + +Although input data can take any form, it is sometimes useful to +describe the record processing capabilities of the system in terms of +a single, canonical input format that gives access to the full +spectrum of structure and flexibility in the system. In Zebra, this +canonical format is an "SGML-like" syntax. + + + +To use the canonical format specify grs.sgml as the record +type, + + + +Consider a record describing an information resource (such a record is +sometimes known as a locator record). It might contain a field +describing the distributor of the information resource, which might in +turn be partitioned into various fields providing details about the +distributor, like this: + + + + + +<Distributor> + <Name> USGS/WRD </Name> + <Organization> USGS/WRD </Organization> + <Street-Address> + U.S. GEOLOGICAL SURVEY, 505 MARQUETTE, NW + </Street-Address> + <City> ALBUQUERQUE </City> + <State> NM </State> + <Zip-Code> 87102 </Zip-Code> + <Country> USA </Country> + <Telephone> (505) 766-5560 </Telephone> +</Distributor> + + + + + +NOTE: The indentation used above is used to illustrate how Zebra +interprets the markup. The indentation, in itself, has no +significance to the parser for the canonical input format, which +discards superfluous whitespace. + + + +The keywords surrounded by <...> are tags, while the +sections of text in between are the data elements. A data element +is characterized by its location in the tree that is made up by the +nested elements. Each element is terminated by a closing tag - +beginning with </, and containing the same symbolic tag-name as +the corresponding opening tag. The general closing tag - <>/ - +terminates the element started by the last opening tag. The +structuring of elements is significant. The element Telephone, +for instance, may be indexed and presented to the client differently, +depending on whether it appears inside the Distributor element, +or some other, structured data element such a Supplier element. + + + +Record Root + + +The first tag in a record describes the root node of the tree that +makes up the total record. In the canonical input format, the root tag +should contain the name of the schema that lends context to the +elements of the record (see section +). +The following is a GILS record that +contains only a single element (strictly speaking, that makes it an +illegal GILS record, since the GILS profile includes several mandatory +elements - Zebra does not validate the contents of a record against +the Z39.50 profile, however - it merely attempts to match up elements +of a local representation with the given schema): + + + + + +<gils> + <title>Zen and the Art of Motorcycle Maintenance</title> +</gils> + + + + + + + +Variants + + +Zebra allows you to provide individual data elements in a number of +variant forms. Examples of variant forms are textual data +elements which might appear in different languages, and images which +may appear in different formats or layouts. The variant system in +Zebra is +essentially a representation of the variant mechanism of +Z39.50-1995. + + + +The following is an example of a title element which occurs in two +different languages. + + + + + +<title> + <var lang lang "eng"> + Zen and the Art of Motorcycle Maintenance</> + <var lang lang "dan"> + Zen og Kunsten at Vedligeholde en Motorcykel</> +</title> + + + + + +The syntax of the variant element is <var class +type value>. The available values for the class and +type fields are given by the variant set that is associated with the +current schema (see section ). + + + +Variant elements are terminated by the general end-tag </>, by +the variant end-tag </var>, by the appearance of another variant +tag with the same class and value settings, or by the +appearance of another, normal tag. In other words, the end-tags for +the variants used in the example above could have been saved. + + + +Variant elements can be nested. The element + + + + + +<title> + <var lang lang "eng"><var body iana "text/plain"> + Zen and the Art of Motorcycle Maintenance +</title> + + + + + +Associates two variant components to the variant list for the title +element. + + + +Given the nesting rules described above, we could write + + + + + +<title> + <var body iana "text/plain> + <var lang lang "eng"> + Zen and the Art of Motorcycle Maintenance + <var lang lang "dan"> + Zen og Kunsten at Vedligeholde en Motorcykel +</title> + + + + + +The title element above comes in two variants. Both have the IANA body +type "text/plain", but one is in English, and the other in +Danish. The client, using the element selection mechanism of Z39.50, +can retrieve information about the available variant forms of data +elements, or it can select specific variants based on the requirements +of the end-user. + + + + + + + +Input Filters + + +In order to handle general input formats, Zebra allows the +operator to define filters which read individual records in their native format +and produce an internal representation that the system can +work with. + + + +Input filters are ASCII files, generally with the suffix .flt. +The system looks for the files in the directories given in the +profilePath setting in the zebra.cfg files. The record type +for the filter is grs.regx.filter-filename +(fundamental type grs, file read type regx, argument +filter-filename). + + + +Generally, an input filter consists of a sequence of rules, where each +rule consists of a sequence of expressions, followed by an action. The +expressions are evaluated against the contents of the input record, +and the actions normally contribute to the generation of an internal +representation of the record. + + + +An expression can be either of the following: + + + + + + +INIT + + +The action associated with this expression is evaluated +exactly once in the lifetime of the application, before any records +are read. It can be used in conjunction with an action that +initializes tables or other resources that are used in the processing +of input records. + + + + +BEGIN + + +Matches the beginning of the record. It can be used to +initialize variables, etc. Typically, the BEGIN rule is also used +to establish the root node of the record. + + + + +END + + +Matches the end of the record - when all of the contents +of the record has been processed. + + + + +/pattern/ + + +Matches a string of characters from the input +record. + + + + +BODY + + +This keyword may only be used between two patterns. It +matches everything between (not including) those patterns. + + + + +FINISH + + +The expression asssociated with this pattern is evaluated +once, before the application terminates. It can be used to release +system resources - typically ones allocated in the INIT step. + + + + + + + +An action is surrounded by curly braces ({...}), and consists of a +sequence of statements. Statements may be separated by newlines or +semicolons (;). Within actions, the strings that matched the +expressions immediately preceding the action can be referred to as +$0, $1, $2, etc. + + + +The available statements are: + + + + + + +begin type [parameter ... ] + + +Begin a new +data element. The type is one of the following: + + + +record + + +Begin a new record. The followingparameter should be the +name of the schema that describes the structure of the record, eg. +gils or wais (see below). The begin record call should +precede +any other use of the begin statement. + + + + +element + + +Begin a new tagged element. The parameter is the +name of the tag. If the tag is not matched anywhere in the tagsets +referenced by the current schema, it is treated as a local string +tag. + + + + +variant + + +Begin a new node in a variant tree. The parameters are +class type value. + + + + + + + + +data + + +Create a data element. The concatenated arguments make +up the value of the data element. The option -text signals that +the layout (whitespace) of the data should be retained for +transmission. The option -element tag wraps the data up in +the tag. The use of the -element option is equivalent to +preceding the command with a begin element command, and following +it with the end command. + + + + +end [type] + + +Close a tagged element. If no parameter is given, +the last element on the stack is terminated. The first parameter, if +any, is a type name, similar to the begin statement. For the +element type, a tag name can be provided to terminate a specific tag. + + + + + + + +The following input filter reads a Usenet news file, producing a +record in the WAIS schema. Note that the body of a news posting is +separated from the list of headers by a blank line (or rather a +sequence of two newline characters. + + + + + +BEGIN { begin record wais } + +/^From:/ BODY /$/ { data -element name $1 } +/^Subject:/ BODY /$/ { data -element title $1 } +/^Date:/ BODY /$/ { data -element lastModified $1 } +/\n\n/ BODY END { + begin element bodyOfDisplay + begin variant body iana "text/plain" + data -text $1 + end record + } + + + + + +If Zebra is compiled with support for Tcl (Tool Command Language) +enabled, the statements described above are supplemented with a complete +scripting environment, including control structures (conditional +expressions and loop constructs), and powerful string manipulation +mechanisms for modifying the elements of a record. Tcl is a popular +scripting environment, with several tutorials available both online +and in hardcopy. + + + +NOTE: Tcl support is not currently available, but will be +included with one of the next alpha or beta releases. + + + +NOTE: Variant support is not currently available in the input +filter, but will be included with one of the next alpha or beta +releases. + + + + + + + +Internal Representation + + +When records are manipulated by the system, they're represented in a +tree-structure, with data elements at the leaf nodes, and tags or +variant components at the non-leaf nodes. The root-node identifies the +schema that lends context to the tagging and structuring of the +record. Imagine a simple record, consisting of a 'title' element and +an 'author' element: + + + + + + TITLE "Zen and the Art of Motorcycle Maintenance" +ROOT + AUTHOR "Robert Pirsig" + + + + + +A slightly more complex record would have the author element consist +of two elements, a surname and a first name: + + + + + + TITLE "Zen and the Art of Motorcycle Maintenance" +ROOT + FIRST-NAME "Robert" + AUTHOR + SURNAME "Pirsig" + + + + + +The root of the record will refer to the record schema that describes +the structuring of this particular record. The schema defines the +element tags (TITLE, FIRST-NAME, etc.) that may occur in the record, as +well as the structuring (SURNAME should appear below AUTHOR, etc.). In +addition, the schema establishes element set names that are used by +the client to request a subset of the elements of a given record. The +schema may also establish rules for converting the record to a +different schema, by stating, for each element, a mapping to a +different tag path. + + + +Tagged Elements + + +A data element is characterized by its tag, and its position in the +structure of the record. For instance, while the tag "telephone +number" may be used different places in a record, we may need to +distinguish between these occurrences, both for searching and +presentation purposes. For instance, while the phone numbers for the +"customer" and the "service provider" are both +representatives for the same type of resource (a telephone number), it +is essential that they be kept separate. The record schema provides +the structure of the record, and names each data element (defined by +the sequence of tags - the tag path - by which the element can be +reached from the root of the record). + + + + + +Variants + + +The children of a tag node may be either more tag nodes, a data node +(possibly accompanied by tag nodes), +or a tree of variant nodes. The children of variant nodes are either +more variant nodes or a data node (possibly accompanied by more +variant nodes). Each leaf node, which is normally a +data node, corresponds to a variant form of the tagged element +identified by the tag which parents the variant tree. The following +title element occurs in two different languages: + + + + + + VARIANT LANG=ENG "War and Peace" +TITLE + VARIANT LANG=DAN "Krig og Fred" + + + + + +Which of the two elements are transmitted to the client by the server +depends on the specifications provided by the client, if any. + + + +In practice, each variant node is associated with a triple of class, +type, value, corresponding to the variant mechanism of Z39.50. + + + + + +Data Elements + + +Data nodes have no children (they are always leaf nodes in the record +tree). + + + +NOTE: Documentation needs extension here about types of nodes - numerical, +textual, etc., plus the various types of inclusion notes. + + + + + + + +Configuring Your Data Model + + +The following sections describe the configuration files that govern +the internal management of data records. The system searches for the files +in the directories specified by the profilePath setting in the +zebra.cfg file. + + + +The Abstract Syntax + + +The abstract syntax definition (also known as an Abstract Record +Structure, or ARS) is the focal point of the +record schema description. For a given schema, the ABS file may state any +or all of the following: + + + + + + + + +The object identifier of the Z39.50 schema associated +with the ARS, so that it can be referred to by the client. + + + + + + +The attribute set (which can possibly be a compound of multiple +sets) which applies in the profile. This is used when indexing and +searching the records belonging to the given profile. + + + + + + +The Tag set (again, this can consist of several different sets). +This is used when reading the records from a file, to recognize the +different tags, and when transmitting the record to the client - +mapping the tags to their numerical representation, if they are +known. + + + + + + +The variant set which is used in the profile. This provides a +vocabulary for specifying the forms of data that appear inside +the records. + + + + + + +Element set names, which are a shorthand way for the client to +ask for a subset of the data elements contained in a record. Element +set names, in the retrieval module, are mapped to element +specifications, which contain information equivalent to the +Espec-1 syntax of Z39.50. + + + + + + +Map tables, which may specify mappings to other database +profiles, if desired. + + + + + + +Possibly, a set of rules describing the mapping of elements to a +MARC representation. + + + + + + +A list of element descriptions (this is the actual ARS of the +schema, in Z39.50 terms), which lists the ways in which the various +tags can be used and organized hierarchically. + + + + + + + + +Several of the entries above simply refer to other files, which +describe the given objects. + + + + + +The Configuration Files + + +This section describes the syntax and use of the various tables which +are used by the retrieval module. + + + +The number of different file types may appear daunting at first, but +each type corresponds fairly clearly to a single aspect of the Z39.50 +retrieval facilities. Further, the average database administrator, +who is simply reusing an existing profile for which tables already +exist, shouldn't have to worry too much about the contents of these tables. + + + +Generally, the files are simple ASCII files, which can be maintained +using any text editor. Blank lines, and lines beginning with a (#) are +ignored. Any characters on a line followed by a (#) are also ignored. +All other +lines contain directives, which provide some setting or value +to the system. Generally, settings are characterized by a single +keyword, identifying the setting, followed by a number of parameters. +Some settings are repeatable (r), while others may occur only once in a +file. Some settings are optional (o), whicle others again are +mandatory (m). + + + + + +The Abstract Syntax (.abs) Files + + +The name of this file type is slightly misleading in Z39.50 terms, +since, apart from the actual abstract syntax of the profile, it also +includes most of the other definitions that go into a database +profile. + + + +When a record in the canonical, SGML-like format is read from a file +or from the database, the first tag of the file should reference the +profile that governs the layout of the record. If the first tag of the +record is, say, <gils>, the system will look for the profile +definition in the file gils.abs. Profile definitions are cached, +so they only have to be read once during the lifespan of the current +process. + + + +When writing your own input filters, the record-begin command +introduces the profile, and should always be called first thing when +introducing a new record. + + + +The file may contain the following directives: + + + + + + +name symbolic-name + + +(m) This provides a shorthand name or +description for the profile. Mostly useful for diagnostic purposes. + + + + +reference OID-name + + +(m) The reference name of the OID for +the profile. The reference names can be found in the util +module of YAZ. + + + + +attset filename + + +(m) The attribute set that is used for +indexing and searching records belonging to this profile. + + + + +tagset filename + + +(o) The tag set (if any) that describe +that fields of the records. + + + + +varset filename + + +(o) The variant set used in the profile. + + + + +maptab filename + + +(o,r) This points to a +conversion table that might be used if the client asks for the record +in a different schema from the native one. + + + +marc filename + + +(o) Points to a file containing parameters +for representing the record contents in the ISO2709 syntax. Read the +description of the MARC representation facility below. + + + +esetname name filename + + +(o,r) Associates the +given element set name with an element selection file. If an (@) is +given in place of the filename, this corresponds to a null mapping for +the given element set name. + + + +any tags + + +(o) This directive specifies a list of +attributes which should be appended to the attribute list given for each +element. The effect is to make every single element in the abstract +syntax searchable by way of the given attributes. This directive +provides an efficient way of supporting free-text searching across all +elements. However, it does increase the size of the index +significantly. The attributes can be qualified with a structure, as in +the elm directive below. + + + +elm path name attributes + + +(o,r) Adds an element +to the abstract record syntax of the schema. The path follows the +syntax which is suggested by the Z39.50 document - that is, a sequence +of tags separated by slashes (/). Each tag is given as a +comma-separated pair of tag type and -value surrounded by parenthesis. +The name is the name of the element, and the attributes +specifies which attributes to use when indexing the element in a +comma-separated list. A ! in +place of the attribute name is equivalent to specifying an attribute +name identical to the element name. A - in place of the attribute name +specifies that no indexing is to take place for the given element. The +attributes can be qualified with field types to specify which +character set should govern the indexing procedure for that field. The +same data element may be indexed into several different fields, using +different character set definitions. See the section +. +The default field type is "w" for +word. + + + + + + +NOTE: The mechanism for controlling indexing is not adequate for +complex databases, and will probably be moved into a separate +configuration table eventually. + + + +The following is an excerpt from the abstract syntax file for the GILS +profile. + + + + + +name gils +reference GILS-schema +attset gils.att +tagset gils.tag +varset var1.var + +maptab gils-usmarc.map + +# Element set names + +esetname VARIANT gils-variant.est # for WAIS-compliance +esetname B gils-b.est +esetname G gils-g.est +esetname F @ + +elm (1,10) rank - +elm (1,12) url - +elm (1,14) localControlNumber Local-number +elm (1,16) dateOfLastModification Date/time-last-modified +elm (2,1) title w:!,p:! +elm (4,1) controlIdentifier Identifier-standard +elm (2,6) abstract Abstract +elm (4,51) purpose ! +elm (4,52) originator - +elm (4,53) accessConstraints ! +elm (4,54) useConstraints ! +elm (4,70) availability - +elm (4,70)/(4,90) distributor - +elm (4,70)/(4,90)/(2,7) distributorName ! +elm (4,70)/(4,90)/(2,10 distributorOrganization ! +elm (4,70)/(4,90)/(4,2) distributorStreetAddress ! +elm (4,70)/(4,90)/(4,3) distributorCity ! + + + + + + + +The Attribute Set (.att) Files + + +This file type describes the Use elements of an attribute set. +It contains the following directives. + + + + + + +name symbolic-name + + +(m) This provides a shorthand name or +description for the attribute set. Mostly useful for diagnostic purposes. + + + +reference OID-name + + +(m) The reference name of the OID for +the attribute set. The reference names can be found in the util +module of YAZ. + + + +ordinal integer + + +(m) This value will be used to represent the +attribute set in the index. Care should be taken that each attribute +set has a unique ordinal value. + + + +include filename + + +(o,r) This directive is used to +include another attribute set as a part of the current one. This is +used when a new attribute set is defined as an extension to another +set. For instance, many new attribute sets are defined as extensions +to the bib-1 set. This is an important feature of the retrieval +system of Z39.50, as it ensures the highest possible level of +interoperability, as those access points of your database which are +derived from the external set (say, bib-1) can be used even by clients +who are unaware of the new set. + + + +att att-value att-name [local-value] + + +(o,r) This +repeatable directive introduces a new attribute to the set. The +attribute value is stored in the index (unless a local-value is +given, in which case this is stored). The name is used to refer to the +attribute from the abstract syntax. + + + + + + +This is an excerpt from the GILS attribute set definition. Notice how +the file describing the bib-1 attribute set is referenced. + + + + + +name gils +reference GILS-attset +include bib1.att +ordinal 2 + +att 2001 distributorName +att 2002 indextermsControlled +att 2003 purpose +att 2004 accessConstraints +att 2005 useConstraints + + + + + + + +The Tag Set (.tag) Files + + +This file type defines the tagset of the profile, possibly by +referencing other tag sets (most tag sets, for instance, will include +tagsetG and tagsetM from the Z39.50 specification. The file may +contain the following directives. + + + + + + +name symbolic-name + + +(m) This provides a shorthand name or +description for the tag set. Mostly useful for diagnostic purposes. + + + +reference OID-name + + +(o) The reference name of the OID for +the tag set. The reference names can be found in the util +module of YAZ. The directive is optional, since not all tag sets +are registered outside of their schema. + + + +type integer + + +(m) The type number of the tagset within the schema +profile (note: this specification really should belong to the .abs +file. This will be fixed in a future release). + + + +include filename + + +(o,r) This directive is used +to include the definitions of other tag sets into the current one. + + + +tag number names type + + +(o,r) Introduces a new +tag to the set. The number is the tag number as used in the protocol +(there is currently no mechanism for specifying string tags at this +point, but this would be quick work to add). The names parameter +is a list of names by which the tag should be recognized in the input +file format. The names should be separated by slashes (/). The +type is th recommended datatype of the tag. It should be one of +the following: + + + + + +structured + + + + + +string + + + + + +numeric + + + + + +bool + + + + + +oid + + + + + +generalizedtime + + + + + +intunit + + + + + +int + + + + + +octetstring + + + + + +null + + + + + + + + + + + +The following is an excerpt from the TagsetG definition file. + + + + + +name tagsetg +reference TagsetG +type 2 + +tag 1 title string +tag 2 author string +tag 3 publicationPlace string +tag 4 publicationDate string +tag 5 documentId string +tag 6 abstract string +tag 7 name string +tag 8 date generalizedtime +tag 9 bodyOfDisplay string +tag 10 organization string + + + + + + + +The Variant Set (.var) Files + + +The variant set file is a straightforward representation of the +variant set definitions associated with the protocol. At present, only +the Variant-1 set is known. + + + +These are the directives allowed in the file. + + + + + + +name symbolic-name + + +(m) This provides a shorthand name or +description for the variant set. Mostly useful for diagnostic purposes. + + + +reference OID-name + + +(o) The reference name of the OID for +the variant set, if one is required. The reference names can be found +in the util module of YAZ. + + + +class integer class-name + + +(m,r) Introduces a new +class to the variant set. + + + +type integer type-name datatype + + +(m,r) Addes a +new type to the current class (the one introduced by the most recent +class directive). The type names belong to the same name space as +the one used in the tag set definition file. + + + + + + +The following is an excerpt from the file describing the variant set +Variant-1. + + + + + +name variant-1 +reference Variant-1 + +class 1 variantId + + type 1 variantId octetstring + +class 2 body + + type 1 iana string + type 2 z39.50 string + type 3 other string + + + + + + + +The Element Set (.est) Files + + +The element set specification files describe a selection of a subset +of the elements of a database record. The element selection mechanism +is equivalent to the one supplied by the Espec-1 syntax of the +Z39.50 specification. In fact, the internal representation of an +element set specification is identical to the Espec-1 structure, +and we'll refer you to the description of that structure for most of +the detailed semantics of the directives below. + + + +NOTE: Not all of the Espec-1 functionality has been implemented yet. +The fields that are mentioned below all work as expected, unless +otherwise is noted. + + + +The directives available in the element set file are as follows: + + + + + + +defaultVariantSetId OID-name + + +(o) If variants are used in +the following, this should provide the name of the variantset used +(it's not currently possible to specify a different set in the +individual variant request). In almost all cases (certainly all +profiles known to us), the name Variant-1 should be given here. + + + +defaultVariantRequest variant-request + + +(o) This directive +provides a default variant request for +use when the individual element requests (see below) do not contain a +variant request. Variant requests consist of a blank-separated list of +variant components. A variant compont is a comma-separated, +parenthesized triple of variant class, type, and value (the two former +values being represented as integers). The value can currently only be +entered as a string (this will change to depend on the definition of +the variant in question). The special value (@) is interpreted as a +null value, however. + + + +simpleElement path ['variant' variant-request] + + +(o,r) This corresponds to a simple element request in Espec-1. The +path consists of a sequence of tag-selectors, where each of these can +consist of either: + + + + + + + + +A simple tag, consisting of a comma-separated type-value pair in +parenthesis, possibly followed by a colon (:) followed by an +occurrences-specification (see below). The tag-value can be a number +or a string. If the first character is an apostrophe ('), this forces +the value to be interpreted as a string, even if it appears to be numerical. + + + + + + +A WildThing, represented as a question mark (?), possibly +followed by a colon (:) followed by an occurrences specification (see +below). + + + + + + +A WildPath, represented as an asterisk (*). Note that the last +element of the path should not be a wildPath (wildpaths don't work in +this version). + + + + + + + + +The occurrences-specification can be either the string all, the +string last, or an explicit value-range. The value-range is +represented as an integer (the starting point), possibly followed by a +plus (+) and a second integer (the number of elements, default being +one). + + + +The variant-request has the same syntax as the defaultVariantRequest +above. Note that it may sometimes be useful to give an empty variant +request, simply to disable the default for a specific set of fields +(we aren't certain if this is proper Espec-1, but it works in +this implementation). + + + + + + +The following is an example of an element specification belonging to +the GILS profile. + + + + + +simpleelement (1,10) +simpleelement (1,12) +simpleelement (2,1) +simpleelement (1,14) +simpleelement (4,1) +simpleelement (4,52) + + + + + + + +The Schema Mapping (.map) Files + + +Sometimes, the client might want to receive a database record in +a schema that differs from the native schema of the record. For +instance, a client might only know how to process WAIS records, while +the database record is represented in a more specific schema, such as +GILS. In this module, a mapping of data to one of the MARC formats is +also thought of as a schema mapping (mapping the elements of the +record into fields consistent with the given MARC specification, prior +to actually converting the data to the ISO2709). This use of the +object identifier for USMARC as a schema identifier represents an +overloading of the OID which might not be entirely proper. However, +it represents the dual role of schema and record syntax which +is assumed by the MARC family in Z39.50. + + + +NOTE: The schema-mapping functions are so far limited to a +straightforward mapping of elements. This should be extended with +mechanisms for conversions of the element contents, and conditional +mappings of elements based on the record contents. + + + +These are the directives of the schema mapping file format: + + + + + + +targetName name + + +(m) A symbolic name for the target schema +of the table. Useful mostly for diagnostic purposes. + + + +targetRef OID-name + + +(m) An OID name for the target schema. +This is used, for instance, by a server receiving a request to present +a record in a different schema from the native one. The name, again, +is found in the oid module of YAZ. + + + +map element-name target-path + + +(o,r) Adds +an element mapping rule to the table. + + + + + + + + +The MARC (ISO2709) Representation (.mar) Files + + +This file provides rules for representing a record in the ISO2709 +format. The rules pertain mostly to the values of the constant-length +header of the record. + + + +NOTE: This will be described better. We're in the process of +re-evaluating and most likely changing the way that MARC records are +handled by the system. + + + + + +Field Structure and Character Sets + + + +In order to provide a flexible approach to national character set +handling, Zebra allows the administrator to configure the set up the +system to handle any 8-bit character set — including sets that +require multi-octet diacritics or other multi-octet characters. The +definition of a character set includes a specification of the +permissible values, their sort order (this affects the display in the +SCAN function), and relationships between upper- and lowercase +characters. Finally, the definition includes the specification of +space characters for the set. + + + +The operator can define different character sets for different fields, +typical examples being standard text fields, numerical fields, and +special-purpose fields such as WWW-style linkages (URx). + + + +The field types, and hence character sets, are associated with data +elements by the .abs files (see above). The file default.idx +provides the association between field type codes (as used in the .abs +files) and the character map files (with the .chr suffix). The format +of the .idx file is as follows + + + + + + +index field type code + + +This directive introduces a new +search index code. The argument is a one-character code to be used in the +.abs files to select this particular index type. An index, roughly, +corresponds to a particular structure attribute during search. Refer +to section . + + + +sort field code type + + +This directive introduces a +sort index. The argument is a one-character code to be used in the +.abs fie to select this particular index type. The corresponding +use attribute must be used in the sort request to refer to this +particular sort index. The corresponding character map (see below) +is used in the sort process. + + + +completeness boolean + + +This directive enables or disables +complete field indexing. The value of the boolean should be 0 +(disable) or 1. If completeness is enabled, the index entry will +contain the complete contents of the field (up to a limit), with words +(non-space characters) separated by single space characters +(normalized to " " on display). When completeness is +disabled, each word is indexed as a separate entry. Complete subfield +indexing is most useful for fields which are typically browsed (eg. +titles, authors, or subjects), or instances where a match on a +complete subfield is essential (eg. exact title searching). For fields +where completeness is disabled, the search engine will interpret a +search containing space characters as a word proximity search. + + + +charmap filename + + +This is the filename of the character +map to be used for this index for field type. + + + + + + +The contents of the character map files are structured as follows: + + + + + + +lowercase value-set + + +This directive introduces the basic +value set of the field type. The format is an ordered list (without +spaces) of the characters which may occur in "words" of +the given type. The order of the entries in the list determines the +sort order of the index. In addition to single characters, the +following combinations are legal: + + + + + + + + +Backslashes may be used to introduce three-digit octal, or +two-digit hex representations of single characters (preceded by x). +In addition, the combinations +\\, \\r, \\n, \\t, \\s (space — remember that real space-characters +may ot occur in the value definition), and \\ are recognised, +with their usual interpretation. + + + + + + +Curly braces {} may be used to enclose ranges of single +characters (possibly using the escape convention described in the +preceding point), eg. {a-z} to entroduce the standard range of ASCII +characters. Note that the interpretation of such a range depends on +the concrete representation in your local, physical character set. + + + + + + +paranthesises () may be used to enclose multi-byte characters - +eg. diacritics or special national combinations (eg. Spanish +"ll"). When found in the input stream (or a search term), +these characters are viewed and sorted as a single character, with a +sorting value depending on the position of the group in the value +statement. + + + + + + + + +uppercase value-set + + +This directive introduces the +upper-case equivalencis to the value set (if any). The number and +order of the entries in the list should be the same as in the +lowercase directive. + + + +space value-set + + +This directive introduces the character +which separate words in the input stream. Depending on the +completeness mode of the field in question, these characters either +terminate an index entry, or delimit individual "words" in +the input stream. The order of the elements is not significant — +otherwise the representation is the same as for the upercase and +lowercase directives. + + + +map value-set target + + +This directive introduces a +mapping between each of the members of the value-set on the left to +the character on the right. The character on the right must occur in +the value set (the lowercase directive) of the character set, but +it may be a paranthesis-enclosed multi-octet character. This directive +may be used to map diacritics to their base characters, or to map +HTML-style character-representations to their natural form, etc. + + + + + + + + + + +Exchange Formats + + +Converting records from the internal structure to en exchange format +is largely an automatic process. Currently, the following exchange +formats are supported: + + + + + + + + +GRS-1. The internal representation is based on GRS-1, so the +conversion here is straightforward. The system will create +applied variant and supported variant lists as required, if a record +contains variant information. + + + + + + +SUTRS. Again, the mapping is fairly straighforward. Indentation +is used to show the hierarchical structure of the record. All +"GRS" type records support both the GRS-1 and SUTRS +representations. + + + + + + +ISO2709-based formats (USMARC, etc.). Only records with a +two-level structure (corresponding to fields and subfields) can be +directly mapped to ISO2709. For records with a different structuring +(eg., GILS), the representation in a structure like USMARC involves a +schema-mapping (see section ), to an +"implied" USMARC schema (implied, +because there is no formal schema which specifies the use of the +USMARC fields outside of ISO2709). The resultant, two-level record is +then mapped directly from the internal representation to ISO2709. See +the GILS schema definition files for a detailed example of this +approach. + + + + + + +Explain. This representation is only available for records +belonging to the Explain schema. + + + + + + +Summary. This ASN-1 based structure is only available for records +belonging to the Summary schema - or schema which provide a mapping +to this schema (see the description of the schema mapping facility +above). + + + + + + +SOIF. Support for this syntax is experimental, and is currently +keyed to a private Index Data OID (1.2.840.10003.5.1000.81.2). All +abstract syntaxes can be mapped to the SOIF format, although nested +elements are represented by concatenation of the tag names at each +level. + + + + + + + + + + + diff --git a/doc/indexdata.xml b/doc/indexdata.xml new file mode 100644 index 0000000..7115d58 --- /dev/null +++ b/doc/indexdata.xml @@ -0,0 +1,63 @@ + +About Index Data and the Zebra Server + + +Index Data is a consulting and software-development enterprise that +specialises in library and information management systems. Our +interests and expertise span a broad range of related fields, and one +of our primary, long-term objectives is the development of a powerful +information management +system with open network interfaces and hypermedia capabilities. + + + +We make this software available free of charge for not-for-profit +purposes, as a service to the networking community, and to further +the development and use of quality software for open network +communication. + + + +If you like this software, and would like to use all or part of it in +a commercial product, or to provide a commercial database service, +please contact us to discuss the details. We'll be happy to answer +questions about the software, and about our services in general. If +you have specific requirements to the software, we'll be glad to offer +our advice - and if you need to adapt the software to a special +purpose, our consulting services and expert knowledge of the software +is available to you at favorable rates. + + + + + +Index Data +Ryesgade 3 +DK-2200 Copenhagen N + + + + + + + +Phone: +45 3536 3672 +Fax : +45 3536 0449 +Email: info@indexdata.dk + + + + + +The Random House College Dictionary, 1975 edition +offers this definition of the +word "Zebra": + + + +Zebra, n., any of several horselike, African mammals of the genus Equus, +having a characteristic pattern of black or dark-brown stripes on +a whitish background. + + + diff --git a/doc/installation.xml b/doc/installation.xml new file mode 100644 index 0000000..14ec6a0 --- /dev/null +++ b/doc/installation.xml @@ -0,0 +1,79 @@ + + +Installation + + +An ANSI C compiler is required to compile the Zebra +server system — gcc works fine if your own system doesn't +provide an adequate compiler. + + + +Unpack the distribution archive. The configure shell script +attempts to guess correct values for various system-dependent variables +used during compilation. It uses those values to create a 'Makefile' in +each directory of Zebra. + + + +To run the configure script type: + + + ./configure + + + + + +The configure script attempts to use C compiler specified by +the CC environment variable. If not set, cc +will be used. The CFLAGS environment variable holds +options to be passed to the C compiler. If you're using a Bourne-shell +compatible shell you may pass something like this: + + + CC=/opt/ccs/bin/cc CFLAGS=-O ./configure + + + + + +When configured build the software by typing: + + + make + + + + + +As an option you may type make depend to create +source file dependencies for the package. This is only needed, +however, if you alter the source. + + + +If successful, two executables have been created in the sub-directory +index. + + + +zebrasrv + + +The Z39.50 server and search engine. + + + + +zebraidx + + +The administrative tool for the search index. + + + + + + + diff --git a/doc/introduction.xml b/doc/introduction.xml new file mode 100644 index 0000000..1fbb3aa --- /dev/null +++ b/doc/introduction.xml @@ -0,0 +1,293 @@ + +Introduction + + +Overview + + +The Zebra system is a fielded free-text indexing and retrieval engine with a +Z39.50 frontend. You can use any commercial or freeware Z39.50 client +to access data stored in Zebra. + + + +The Zebra server is our first step towards the development of a fully +configurable, open information system. Eventually, it will be paired +off with a powerful Z39.50 client to support complex information +management tasks within almost any application domain. We're making +the server available now because it's no fun to be in the open +information retrieval business all by yourself. We want to allow +people with interesting data to make their things +available in interesting ways, without having to start out +by implementing yet another protocol stack from scratch. + + + +This document is an introduction to the Zebra system. It will tell you +how to compile the software, and how to prepare your first database. +It also explains how the server can be configured to give you the +functionality that you need. + + + +If you find the software interesting, you should join the support +mailing-list by sending email to zebra-request@indexdata.dk. + + + + + +Features + + +This is a list of some of the most important features of the +system. + + + + + + + + +Supports updating - records can be added and deleted without +rebuilding the index from scratch. +The update procedure is tolerant to crashes or hard interrupts +during register updating - registers can be reconstructed following a crash. +Registers can be safely updated even while users are accessing the server. + + + + + + +Supports large databases - files for indices, etc. can be +automatically partitioned over multiple disks. + + + + + + +Supports arbitrarily complex records - base input format is an +SGML-like syntax which allows nested (structured) data elements, as +well as variant forms of data. + + + + + + +Supports random storage formats. A system of input filters driven by +regular expressions allows you to easily process most ASCII-based +data formats. SGML, ISO2709 (MARC), and raw text are also supported. + + + + + + +Supports boolean queries as well as relevance-ranking (free-text) +searching. Right truncation and masking in terms are supported, as +well as full regular expressions. + + + + + + +Supports multiple concrete syntaxes +for record exchange (depending on the configuration): GRS-1, SUTRS, +ISO2709 (*MARC). Records can be mapped between record syntaxes and +schema on the fly. + + + + + + +Supports approximate matching in registers (ie. spelling mistakes, +etc). + + + + + + + + + +Protocol support: + + + + + + + + +Protocol facilities: Init, Search, Retrieve, Browse and Sort. + + + + + + +Piggy-backed presents are honored in the search-request. + + + + + + +Named result sets are supported. + + + + + + +Easily configured to support different application profiles, with +tables for attribute sets, tag sets, and abstract syntaxes. +Additional tables control facilities such as element mappings to +different schema (eg., GILS-to-USMARC). + + + + + + +Complex composition specifications using Espec-1 are partially +supported (simple element requests only). + + + + + + +Element Set Names are defined using the Espec-1 capability of the +system, and are given in configuration files as simple element +requests (and possibly variant requests). + + + + + + +Some variant support (not fully implemented yet). + + + + + + +Using the YAZ toolkit for the protocol implementation, the +server can utilise a plug-in XTI/mOSI implementation (not included) to +provide SR services over an OSI stack, as well as Z39.50 over TCP/IP. + + + + + + +Zebra runs on most Unix-like systems as well as Windows NT - a binary +distribution for Windows NT is forthcoming - so far, the installation +requires MSVC++ to compile the system (we use version 5.0). + + + + + + + + + + + +Future Work + + +This is a beta-release of the software, to allow you to look at +it - try it out, and assess whether it can be of use to you. + + + +These are some of the plans that we have for the software in the near +and far future, approximately ordered after their relative importance. +Items marked with an +asterisk will be implemented before the +last beta release. + + + + + + + + +*Complete the support for variants. + + + + + + +*Finalize the data element include facility +to support multimedia data elements in records. + + + + + + +Add more sophisticated relevance ranking mechanisms. Add support for soundex +and stemming. Add relevance feedback support. + + + + + + +Complete EXPLAIN support. + + + + + + +Add support for very large records by implementing segmentation and/or +variant pieces. + + + + + + +Support the Item Update extended service of the protocol. + + + + + + +We want to add a management system that allows you to +control your databases and configuration tables from a graphical +interface. We'll probably use Tcl/Tk to stay platform-independent. + + + + + + + + + +Programmers thrive on user feedback. If you are interested in a facility that +you don't see mentioned here, or if there's something you think we +could do better, please drop us a mail. If you think it's all really +neat, you're welcome to drop us a line saying that, too. You'll find +contact info at the end of this file. + + + + diff --git a/doc/license.xml b/doc/license.xml new file mode 100644 index 0000000..07002b0 --- /dev/null +++ b/doc/license.xml @@ -0,0 +1,54 @@ + +License + + +Copyright © 1995-2002 Index Data. + + + +All rights reserved. + + + +Use and redistribution in source or binary form, with or without +modification, of any or all of this software and documentation is +permitted, provided that the following conditions are met: + + + +1. This copyright and permission notice appear with all copies of the +software and its documentation. Notices of copyright or attribution +which appear at the beginning of any file must remain unchanged. + + + +2. The names of Index Data or the individual authors may not be used to +endorse or promote products derived from this software without specific +prior written permission. + + + +3. Source code or binary versions of this software and its +documentation may be used freely in not-for-profit applications. For +profit applications - such as providing for-pay database services, +marketing a product based in whole or in part on this software or its +documentation, or generally distributing this software or its +documentation under a different license - requires a commercial +license from Index Data. The software may be installed and used for +evaluation purposes in conjunction with a commercial application for a +trial period of no more than 60 days. + + + +THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, +EXPRESS, IMPLIED, OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY +WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. +IN NO EVENT SHALL INDEX DATA BE LIABLE FOR ANY SPECIAL, INCIDENTAL, +INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR +NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF +LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE +OF THIS SOFTWARE. + + + diff --git a/doc/xml.dcl b/doc/xml.dcl new file mode 100644 index 0000000..fed2103 --- /dev/null +++ b/doc/xml.dcl @@ -0,0 +1,179 @@ +" + PIC "?>" + SHORTREF NONE + + NAMES + SGMLREF + + QUANTITY NONE + + ENTITIES + "amp" 38 + "lt" 60 + "gt" 62 + "quot" 34 + "apos" 39 + + FEATURES + MINIMIZE + DATATAG NO + OMITTAG NO + RANK NO + SHORTTAG + STARTTAG + EMPTY NO + UNCLOSED NO + NETENABL IMMEDNET + ENDTAG + EMPTY NO + UNCLOSED NO + ATTRIB + DEFAULT YES + OMITNAME NO + VALUE NO + EMPTYNRM YES + IMPLYDEF + ATTLIST NO + DOCTYPE NO + ELEMENT NO + ENTITY NO + NOTATION NO + LINK + SIMPLE NO + IMPLICIT NO + EXPLICIT NO + OTHER + CONCUR NO + SUBDOC NO + FORMAL NO + URN NO + KEEPRSRE YES + VALIDITY TYPE + ENTITIES + REF ANY + INTEGRAL YES + APPINFO NONE + SEEALSO "ISO 8879:1986//NOTATION + Extensible Markup Language (XML) 1.0//EN" +> diff --git a/doc/zebra.xml.in b/doc/zebra.xml.in new file mode 100644 index 0000000..341dee9 --- /dev/null +++ b/doc/zebra.xml.in @@ -0,0 +1,43 @@ + + + + + + +]> + + + +Zebra Server - Administrators's Guide and Reference + +SebastianHammer + + +1995-2002 +Index Data + + + +The Zebra information server combines a versatile fielded/free-text +search engine with a Z39.50-1995 frontend to provide a powerful and flexible +information management system. This document explains the procedure for +installing and configuring the system, and outlines the possibilities +for managing data and providing Z39.50 +services with the software. + + +This manual covers version @VERSION@ of Zebra. + + + + + +&chap-introduction; +&chap-installation; +&chap-administration; +&app-license; +&app-indexdata; + + diff --git a/doc/zebrahtml.dsl.in b/doc/zebrahtml.dsl.in new file mode 100644 index 0000000..842ff4f --- /dev/null +++ b/doc/zebrahtml.dsl.in @@ -0,0 +1,26 @@ + +]> + + + + + +(define %use-id-as-filename% #t) +(define %output-dir% "html") +(define %html-ext% ".html") +(define %shade-verbatim% #t) + + + + + + + diff --git a/doc/zebraprint.dsl.in b/doc/zebraprint.dsl.in new file mode 100644 index 0000000..fce3256 --- /dev/null +++ b/doc/zebraprint.dsl.in @@ -0,0 +1,21 @@ + +]> + + + + + + + + + + + -- 1.7.10.4