improve READMEs

ssp · Mar 3, 2014 · b4b0323 · b4b0323
1 parent d7fcf92
commit b4b0323
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 6 deletions.
diff --git a/README.markdown b/README.markdown
@@ -4,27 +4,29 @@ This repository contains the configuration files for Index Data’s [pazpar2](ht
 
 The files were created for [SUB Göttingen](http://www.sub.uni-goettingen.de) and [Universitätsbibliothek Greifswald](http://www.uni-greifswald.de/bibliothek.html).
 
-The configuration requires at least pazpar2 version 1.6.39 to work.
+The configuration requires at least pazpar2 1.6.39 with yaz 5.0.18 to work.
 
 
 ## Contents
 * `HGW.xml`: server configuration for Universitätsbibliothek Greifswald
 * `SUB.xml`: server configuration for SUB Göttingen
 * `test.xml`: test server configuration
 * `services/`: folder with service configuration files:
-	* `HGW/`: services used by Universitätsbibliothek Greifswald’s server
-	* `SUB/`: services used by SUB Göttingen’s server
-	* `test/`: test services
-	* `metadata/default.xml`: metadata configurations included by the services to avoid redundancy
+	* `HGW/`: folder with service configurations used by Universitätsbibliothek Greifswald’s server
+	* `SUB/`: folder with service configurations used by SUB Göttingen’s server
+	* `test/`: folder with test services
+	* `metadata/`: folder with metadata configurations, included by the services to avoid redundancy; `default.xml` pre-configures the typical fields we expect for use with `tmarc.xsl` and with the [JavaScript client](https://github.com/ssp/pazpar2-js-client).
 * `settings/`: folder with settings used by the services:
 	* file names try to be mildly descriptive, with library union names or country codes
+	* `secrets/`: submodule with access credentials not commited in this repository
 	* `testing/`: folder with experimental, deprecated or unused settings
 * `xsl/`: folder with transformation XSLTs to normalise the loaded data with subfolders:
 	* `convert/`: conversion to pz:metadata tags
 		* MARC: symlinks to extended version of `tmarc.xsl` with a few additional fields; `MarcXML2TurboMARC.xsl` can provide conversion from MARCXML
 		* UNIMARC: `tunimarc.xsl` covers by far more fields and details than pazpar2’s unimarc.xsl; `MarcXML2TurboMARC.xsl` can provide conversion from UNIMARCXML
 		* MAB: `tmab.xsl` tries to import MAB data in TurboMARC Syntax, `tmarc-to-tmab.xsl` can help fixing parsing problems
 		* Solr: `solr.xsl` symlinks to an improved version of pazpar2’s `solr-pz2.xsl`
+		* Plain XML: `fields.xsl` expects a flat XML file and maps tag names to `pz:metadata/@type`s
 	* `target/`: target specific transformations; file names begin like those of the settings files using them; file names ending in `-pre` indicate they operate on raw data from the server, file names ending in `-post` work on the pz:metadata model
 	* `pz/`: generic transformations on the pz:metadata model
 	* `tmarc/`: generic transformations for TurboMARC
@@ -36,8 +38,9 @@ The configuration requires at least pazpar2 version 1.6.39 to work.
 * git submodules:
 	* [`pazpar2`](http://git.indexdata.com/?p=pazpar2.git) by Index Data
 	* [`yaz`](http://git.indexdata.com/?p=yaz.git): library used by pazpar2
+	* [`pazpar2-etc/`](https://github.com/ssp/pazpar2-etc): customised files (e.g. `tmarc.xsl`) from the `pazpar2/etc` folder. These are kept in a separate repository to enable using a cleanly checked out version of the software.
 	* [`pazpar2-access`](ttps://github.com/subugoe/pazpar2-access): small script that can (de-)activate databases based on the user’s IP address
-* The [subrepository in `pazpar2-etc/`](https://github.com/ssp/pazpar2-etc) contains customised files (e.g. `tmarc.xsl`) from the `pazpar2/etc` folder. These are kept in a separate repository to enable using a cleanly checked out version of the software.
+	* `settings/secrets`: access credentials, not published
 * The folder `conf/` contains configuration files to help installing the pazpar2 service on a server:
 	* `pazpar2.init`: init script for SUSE Linux
 	* `pazpar2.logrotate`: logrotate configuration file

diff --git a/services/HGW/README.md b/services/HGW/README.md
@@ -0,0 +1,85 @@
+# pazpar2 Konfiguration für vifanord
+
+2014: Sven-S. Porst <ssp-web@earthlingsoft.net>
+
+
+## Einrichtung
+Auf dem Server ist aus dem Paketen von Index Data pazpar2 installiert. Es wird mindestens pazpar2 1.6.39 mit yaz 5.0.18 benötigt. pazpar2 installiert ein fertiges init Skript, mit dem der Dienst gestartet und beendet werden kann.
+
+Die Konfigurationsdateien liegen in `/etc/pazpar2`. Zu diesem Ordner ist dieses Repository mit Subrepositories als Ordner `vifanord-config` hinzugefügt. Weiterhin sind einige Symlinks hinzugefügt, bzw. Dateien ersetzt.
+
+   > ls -l /etc/pazpar2/
+
+   -rw-r--r--  1 itvifa itvifa   182 Okt 28 16:55 ap2pazpar2.cfg
+   -rw-r--r--  1 itvifa itvifa   229 Jan 18  2013 ap2pazpar2-js.cfg
+   -rw-r--r--  1 itvifa itvifa  3272 Aug 13  2013 cf.xsl
+   drwxr-xr-x 11 itvifa itvifa  4096 Jan 29  2013 conf
+   -rw-r--r--  1 itvifa itvifa  6682 Jan 18  2013 dads-pz2.xsl
+   -rw-r--r--  1 itvifa itvifa  8516 Jan 18  2013 danmarc2.xsl
+   -rw-r--r--  1 itvifa itvifa  2084 Jan 18  2013 dc.xsl
+   -rw-r--r--  1 root   root    2588 Jan  7 14:04 dkabm.xsl
+   -rw-r--r--  1 itvifa itvifa   646 Jan 18  2013 marc21-ourl.xsl
+   -rw-r--r--  1 itvifa itvifa 16259 Jan 18  2013 marc21.xsl
+   -rw-r--r--  1 itvifa itvifa  9991 Jan 18  2013 marc22.xsl
+   -rw-r--r--  1 itvifa itvifa  2776 Jan 18  2013 MarcXML2TurboMarc.xsl
+   -rw-r--r--  1 itvifa itvifa  1995 Jan 18  2013 oai_dc.xsl
+   -rw-r--r--  1 itvifa itvifa  1695 Apr 26  2013 opac_turbomarc.xsl
+   -rw-r--r--  1 itvifa itvifa  1693 Apr 26  2013 opac.xsl
+   -rw-r--r--  1 itvifa itvifa   885 Jan 18  2013 pp2out-to-carrot2.xsl
+   -rw-r--r--  1 itvifa itvifa  5185 Jan 18  2013 primo-pz2.xsl
+   -rw-r--r--  1 itvifa itvifa  4875 Jan 18  2013 pz2-ourl-base.xsl
+   -rw-r--r--  1 itvifa itvifa  2895 Jan 18  2013 pz2-ourl-marc21.xsl
+   -rw-r--r--  1 itvifa itvifa   648 Jan 18  2013 pz2-solr.xsl
+   -rw-r--r--  1 itvifa itvifa  1788 Jan 18  2013 server-status-nagios.xsl
+   lrwxrwxrwx  1 itvifa itvifa    23 Mär  3 11:31 __server.xml -> vifanord-config/HGW.xml__
+   lrwxrwxrwx  1 itvifa itvifa    24 Mär  3 11:31 __services -> vifanord-config/services__
+   drwxr-xr-x  2 itvifa itvifa  4096 Feb 20 10:35 services-available
+   drwxr-xr-x  2 itvifa itvifa    25 Jan 29  2013 services-enabled
+   lrwxrwxrwx  1 itvifa itvifa    25 Mär  3 11:31 __settings -> vifanord-config/settings/__
+   -rw-r--r--  1 itvifa itvifa  1790 Aug 30  2013 solr-pz2.xsl
+   -rw-r--r--  1 itvifa itvifa 26719 Aug 13  2013 tmarc.xsl
+   -rw-r--r--  1 itvifa itvifa  3002 Jan 18  2013 unimarc.xsl
+   -rw-r--r--  1 itvifa itvifa   358 Jan 18  2013 usmarc.xsl
+   drwxr-xr-x 11 itvifa itvifa  4096 Feb 28 11:45 __vifanord-config__
+   lrwxrwxrwx  1 itvifa itvifa    20 Mär  3 11:31 __xsl -> vifanord-config/xsl/__
+
+
+Die Struktur des Repositories `vifanord-config` ist in dessen Readme beschrieben. Das Folgende bezieht sich auf seinen Inhalt.
+
+
+## Server
+
+Der pazpar2 Server lädt standardmäßig die Datei `/etc/pazpar2/server.xml`, also die Datei `vifanord-config/HGW.xml`. Sie bindet die Konfigurationsdateien für die verschiedenen pazpar2 Services für vifanord ein.
+
+[Dokumentation der pazpar2 Konfigurationsdateien](http://www.indexdata.com/pazpar2/doc/pazpar2_conf.html)
+
+## Dienste
+
+Pazpar2 bietet verschiedene Dienste (Services) an. Ein solcher Dienst ist eine vorkonfigurierte Metasuche, bestehend aus der Konfiguration der abzufragenden Server und des internen Metadatenmodells.
+
+Die Dienstkonfigurationen für vifanord liegen im Ordner `services/HGW`. Es gibt für jeden der 12 vifanord Sucheinstiege einen Dienst mit Namen `vifanord[-themen|geo|ir][-balt|-nord]`.
+
+Die Dienste binden vorkonfigurierte Einstellunge für die verschiedenen Server ein, die im Ordner `settings` liegen. So können die Konfigurationen wiederverwendet werden.
+
+Das Metadatenmodell beschreibt die von pazpar2 genutzten Felder und konfiguriert die gelieferten Facetten sowie die Deduplizierung. Es ist hauptsächlich durch `metadata/default.xml` beschrieben, mit spezifischen Anpassungen für vifanord in `metadata/vifanord-extras.xml`. Da bei pazpar2s Metadatenkonfiguration der zuerst eingelesene Wert gilt, ist es wichtig, daß diese Datei _vor_ der allgemeinen eingebunden wird.
+
+
+## Einstellungen
+
+Im Ordner `settings` sind die Server Konfigurationen möglichst generisch abgelegt. Intern identifiziert pazpar2 die Einstellungen über das `target` Attribut. Es kann mit einem `*` enden, um eine Einstellung auf alle Targets, die gleich beginnen anzuwenden. Dieses Attribut wird auch verwendet, um die lokalisierten Namen zur Anzeige zu erzeugen (siehe `facet-xtargets` in  [pazpar2-vifanord.js](https://github.com/ssp/vifanord-pazpar2-typo3/blob/master/pazpar2-vifanord.js)).
+
+Um von pazpar2 genutzt zu werden, muß für ein Target die `pz:name` Einstellung gesetzt sein. Mit der `pz:allow` Einstellung kann das Target durch den Wert 0/1 deaktiviert/aktiviert werden.
+
+Die generelle Konfiguration ist in der [pazpar2 Dokumentation](http://www.indexdata.com/pazpar2/doc/pazpar2_conf.html) beschrieben. Über die Verbindung zur Server hinaus besonders wichtige Felder für uns sind:
+
+* `pz:cclmap:*`: Konfiguration der pazpar2 CCL Abfrageschlüssel durch Angabe der zugehörigen Serverabfrage. Für die vifanord Oberfläche erwarten wir, daß `term`, `title`, `person`, `subject`, `date` konfiguriert sind. Für die thematische Suche nutzen wir (in den zugehörigen Targets) zusätzlich `ddc-ir`, `ddc-t`, `ddc-g` und `lsg`.
+* `pz:limitmap:*`: (selten) falls die Möglichkeit besteht bei Auswahl einer Facette, die Suche auf dem Server verfeinert neu zu starten, kann hier für den Facettennamen angegeben werden, welche Abfragebedingung hinzugefügt werden soll.
+* `pz:maxrecs`: Maximale Anzahl der vom Server zu ladenden Treffer.
+* `pz:allow`: Wird das Target in die Suche eingebunden (1) oder nicht (0)
+* `pz:xslt`: Kommaseparierte Liste von Pfaden zu XSLT Dateien. Die Records vom Server werden in dieser Reihenfolge durch XSL in das interne Metadatenmodell transformiert.
+* `catalogueURLHintPrefix`: URL, die durch Anhängen des `id` Feldes eine URL zur Webseite für den zugehörigen Record wird.
+
+
+## XSL
+
+Pazpar2s Datennormalisierung findet mit XSL statt. Im Ordner `xsl` befindt sich eine Sammlung verschiedener Transformationen, die die häufig benötigten Schritte ausführen.