=====================
-MKWS accesses targets using the Pazpar2 metasearching engine, almost
-always fronted by the Service Proxy to manage target selection. This
-document assumes the SP is used, and so that a library of targets is
-available, maintained using an instance of MKAdmin (often
-http://mkc-admin.indexdata.com/console/)
-
+MKWS accesses targets using the Pazpar2 metasearching engine. Although
+Pazpar2 can be used directly, using a statically configured set of
+targets, this usage is unusual. More often, Pazpar2 is fronted by the
+Service Proxy (SP), which manages authentication, sessions, target
+selection, etc.
-1. Selecting targets within the library
----------------------------------------
+This document assumes the SP is used, and explains how to go about
+making a set of targets (a "library") available, how to connect your
+MKWS application to that library, and how to choose which of the
+available targets to use.
-MKWS applications can choose what subset of the library's targets to
-use, by means of several alternative settings on individual widgets or
-in the mkws_config structure:
-* targets -- contains a Pazpar2 targets string, typically of the form
- "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
- target IDs.
-
- At present, these IDs can take one of two forms, depending on the
- configuration of the Service Proxy being used: they may be based on
- ZURLs, so a typical value would be something like:
- pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
- Or they may be UDBs, so a typical value would be something like:
- pz:id=brown|artstor
+1. Maintaining the library
+--------------------------
-* targetfilter -- contains a CQL query which is used to find relevant
- targets from the relvant library. For example,
- udb==Google_Images
- Or
- categories=news
-
-* target -- contains a single UDB, that of the sole target to be
- used. For example
- Google_Images
- This is merely syntactic sugar for "targetfilter" with the query
- udb==NAME
+### and so that a library of targets
+is available, maintained using an instance of MKAdmin (often
+http://mkc-admin.indexdata.com/console/)
2. Authenticating onto the library
target selection within the set that it makes available can be done
using the mechanisms above.
+
+3. Choosing targets from the library
+------------------------------------
+
+MKWS applications can choose what subset of the library's targets to
+use, by means of several alternative settings on individual widgets or
+in the mkws_config structure:
+
+* targets -- contains a Pazpar2 targets string, typically of the form
+ "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
+ target IDs.
+
+ At present, these IDs can take one of two forms, depending on the
+ configuration of the Service Proxy being used: they may be based on
+ ZURLs, so a typical value would be something like:
+ pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
+ Or they may be UDBs, so a typical value would be something like:
+ pz:id=brown|artstor
+
+* targetfilter -- contains a CQL query which is used to find relevant
+ targets from the relvant library. For example,
+ udb==Google_Images
+ Or
+ categories=news
+
+* target -- contains a single UDB, that of the sole target to be
+ used. For example
+ Google_Images
+ This is merely syntactic sugar for "targetfilter" with the query
+ udb==NAME
+
+