This file -- not valid XML -- contains illustrative examples of the configuration

file format I have in mind. It is basically a mechanism to allow you to set
multiple name-value pairs for targets -- possibly user specific. The various forms
are intended to support various activities -- like setting system-wide defaults,
overriding settings for one user or target, setting up values for a specific target,
etc. There's even a verbose form that would lend itself well to dumping values
out of a relational database... indeed, it's possible to imagine an extension that
would allow pazpar2 to access settings from an RDBMS, although this is not planned
at present.

diff --git a/etc/example-settings b/etc/example-settings
new file mode 100644 (file)
index 0000000..97949da
--- /dev/null
+++ b/etc/example-settings
@@ -0,0 +1,104 @@
+
+Each of the following examples is an example target settings file. On startup, 
+pazpar2 will read any number of these files recursively from a directory hierarchy.
+Explanations for the examples below.
+
+The following file explicitly sets name=value for a whole bunch of targets for a
+bunch of users.. I don't imagine this format will be used much for human
+entry, but it might be used to export settings from a relational database.. it is
+also there as one extreme form of a generic format.
+
+If user is omitted, the setting applies to any user. For target, there are two wildcard
+forms: * matches any target not otherwise matched, and xx/* matches any database on a given
+host. A setting for an explicit host/db always overrides a wildcard setting.
+
+<settings>
+  <set target="xx" name="xx" value="xx" user="xx"/>
+  <set target="xx" name="xx" value="xx" user="xx"/>
+  <set target="xx" name="xx" value="xx" user="xx"/>
+</settings>
+
+More useful, you can group a number of settings about a target into one file like this.
+This comes closer to the conventional target setting files we're used to. 
+
+<settings target="xx">
+  <set name="xx" value="xx"/>
+  <set name="xx" value="xx"/>
+  <set name="xx" value="xx"/>
+</settings>
+
+This file sets a number of name=value pairs for a list of targets. A typical example might
+be to associate all these targets with a specific category or type, or to otherwise make
+them part of a set -- like 'all full-text', 'all free-access', etc.
+
+<settings name="xx" value="xx">
+  <set target="xx"/>
+  <set target="xx"/>
+  <set target="xx"/>
+  <set target="xx"/>
+</settings>
+
+Here's the shortest possible file.. it sets one name=value for one target
+
+<settings target="xx" name="xx" value="xx" user="xx"/>
+
+This sets different values for a given named setting (attribute) for one target.
+
+<settings name="xx" target="xx">
+  <set value="xx"/>
+  <set value="xx"/>
+  <set value="xx"/>
+</settings>
+
+This sets different values for one attribute for different targets 
+
+<settings name="xx">
+  <value>xx</value>
+  <value>xx</value>
+  <set target="xx"/>
+  <set target="xx"/>
+  <set target="xx"/>
+</settings>
+
+This sets one or more named values for a set of targets.
+
+<settings>
+  <target>xx</target>
+  <target>xx</target>
+  <target>xx</target>
+  <set name="xx" value="xx"/>
+  <set name="xx" value="xx"/>
+</settings>
+
+This is a more concrete example.. it allows specific users access to a given target.
+
+<settings name="pz:allow" target="xx" value="yes">
+  <set user="xx"/>
+  <set user="xx"/>
+  <set user="xx"/>
+</settings>
+
+While this default setting disallows access to anything for everybody not otherwise
+permitted...
+
+// Whitelist default -- disallow all access
+<settings name="pz:allow" target="*" value="no"/>
+
+.. except these 'free' targets which are open to anyone.
+
+// Except these ones
+<settings name="pz:allow" value="yes">
+  <set target="xx"/>
+  <set target="xx"/>
+  <set target="xx"/>
+</settings>
+
+The setting below sets a default record normalization stylesheet. Yes, values can be simple
+strings, or they can be XML trees.
+
+<settings xmlns="http://www.indexdata.com/pazpar2/1" target="*" name="pz:normalize">
+  <set>
+    <xsl:stylesheet xmlns:xsl="xxx" ..>
+    </xsl:stylesheet>
+  </set>
+</settings>