Complete rewrite of index.html, up to date with present code. Clean up into proper...

diff --git a/doc/index.markdown b/doc/index.markdown
index ee584db..bd152b0 100644 (file)
--- a/doc/index.markdown
+++ b/doc/index.markdown
@@ -1,6 +1,6 @@
 % MKWS: the MasterKey Widget Set
-<!---% Mike Taylor
-% June 2014-->
+% Mike Taylor
+% October 2014
 
 
 Add metasearching to your web-site painlessly
@@ -11,7 +11,7 @@ an existing web-site with customised searching across multiple
 sources, ranking and merging the results.
 
 As much of the searching functionality as possible is hosted on
-<http://mkws.indexdata.com/> so that very simple applications such as
+`http://mkws.indexdata.com/` so that very simple applications such as
 <http://example.indexdata.com/simple.html> can have MasterKey
 searching with minimal effort.  All you need to do is pull in our
 JavaScript and optional stylesheet, then add `<div>`s to your page
@@ -36,7 +36,7 @@ A minimal example
 -----------------
 
 Here is a completely functional (though ugly) MKWS-based
-searching application:
+searching application [[link]](http://example.indexdata.com/minimal.html)
 
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
        <div class="mkwsSearch"></div>
@@ -48,102 +48,97 @@ else is refinement.
 Configuring a client (short version)
 ------------------------------------
 
-The application's HTML must contains the following elements as well as
+The application's HTML must contain the following elements as well as
 whatever makes up the application itself:
 
-Prerequisites:
-
-~~~
-       <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
-~~~
+       <link rel="stylesheet" href="http://mkws.indexdata.com/mkws.css" />
+
+These lines pull in JavaScript code and the default styles. (The
+latter may be omitted or replaced with application-specific styles for
+the widgets.)
 
 Then the following special `<div>`s can be added (with no content), and
 will be filled in by MKWS:
 
-* `<div id="mkwsSwitch"></div>` -- switch between record and target views
-* `<div id="mkwsLang"></div>  ` -- switch between English, Danish and German
-* `<div id="mkwsSearch"></div>` -- search box and button
-* `<div id="mkwsResults"></div>` -- result list, including pager/sorting
-* `<div id="mkwsTargets"></div>` -- target list, including status
-* `<div id="mkwsStat"></div>` -- summary statistics
+* `<div class="mkwsSearch"></div>` -- search box and button
+* `<div class="mkwsResults"></div>` -- result list, including pager/sorting
+* `<div class="mkwsStat"></div>` -- summary statistics
+* `<div class="mkwsSwitch"></div>` -- switch between record and target views
+* `<div class="mkwsTargets"></div>` -- target list, including status
+* `<div class="mkwsLang"></div>  ` -- switch between languages, e.g. English, Danish and German
 
 You can configure and control the client by creating an `mkws_config`
-object before loading the widget-set. Here is an example showing how
-to use options to offer a choice between English and German UI
-languages, and to default to sorting by title ascending:
-
-~~~
-    <script type="text/javascript">
-      var mkws_config = {
-        lang_options: ["en", "de" ],
-        sort_default: "title:1"
-      };
-    </script>
-~~~
-
-For much more detail, see:
-[Embedded metasearching with the MasterKey Widget Set](mkws-manual.html)
-
-Documentation
--------------
-
-* This file.
-  [<a href="index.pdf">PDF version</a>]
-* The <a href="mkws-manual.html">MKWS manual, including a reference section.</a>
-  [<a href="mkws-manual.pdf">PDF version</a>]
-* The <a href="mkws-developer.html">MKWS developers' guide.</a>
-  [<a href="mkws-developer.pdf">PDF version</a>]
-
-Tools
------
+object. Here is an example showing how to use options to offer a
+choice between English and German UI languages, and to default to
+sorting by title ascending:
+
+       <script type="text/javascript">
+         var mkws_config = {
+           lang_options: ["en", "de" ],
+           sort_default: "title:1"
+         };
+       </script>
+
+Detailed documentation
+----------------------
+
+Apart from [this file](index.html) and its [PDF version](index.pdf):
+
+* The [MKWS manual, including a reference section](mkws-manual.html)
+  [[PDF version]](mkws-manual.pdf)
+* The [MKWS developers' guide](mkws-developer.html)
+  [[PDF version]](mkws-developer.pdf)
+
+Widget files
+------------
 
 Here are the files that this web-site provides:
 
-* <a href="mkws.js">mkws.js</a> --
+* [mkws.js](mkws.js) --
   JavaScript code that powers the MasterKey Widget Set
-* <a href="pazpar2/js/pz2.js">pazpar2/js/pz2.js</a> --
+* [pazpar2/js/pz2.js](pazpar2/js/pz2.js) --
   Low-level JavaScript library for access to the MasterKey web
   service.
-* <a href="handlebars-v2.0.0.js">handlebars-v2.0.0.js</a> --
+* [handlebars-v2.0.0.js](handlebars-v2.0.0.js) --
   A local copy of
-  <a href="http://handlebarsjs.com/">the Handlebars templating library</a>,
+  [the Handlebars templating library](//handlebarsjs.com/),
   since it doesn't like to be hotlinked.
-* Local copy of <a href="jquery-1.10.0.min.js">jquery-1.10.0.min.js</a>
-* Local copy of <a href="jquery.json-2.4.js">jquery.json-2.4.js</a>
-* <a href="mkws-complete.js">mkws-complete.js</a> --
+* Local copy of [jquery-1.10.0.min.js](jquery-1.10.0.min.js)
+* Local copy of [jquery.json-2.4.js](jquery.json-2.4.js)
+* [mkws-complete.js](mkws-complete.js) --
   A single large JavaScript file containing everything needed for
   MKWS to work: the widget-set itself, the API library, and
   the prerequisites jQuery and Handlebars.
-* <a href="mkws.css">mkws.css</a> --
+* [mkws.css](mkws.css) --
   A stylesheet which styles only MasterKey widgets, and does not
   otherwise interfere with application-site's styles.
 
 Minified versions of the MKWS JavaScript files are also available:
 
-* <a href="mkws.min.js">mkws.min.js</a>
-* <a href="mkws-complete.min.js">mkws-complete.min.js</a>
+* [mkws.min.js](mkws.min.js)
+* [mkws-complete.min.js](mkws-complete.min.js)
 
 ### Specific versions
 
 The links above to the various forms of the widget-set JavaScript
-(<a href="mkws.js">mkws.js</a>,
-<a href="mkws-complete.js">mkws-complete.js</a>,
-<a href="mkws.min.js">mkws.min.js</a>
+([mkws.js](mkws.js),
+[mkws-complete.js](mkws-complete.js),
+[mkws.min.js](mkws.min.js)
 and
-<a href="mkws-complete.min.js">mkws-complete.min.js</a>)
+[mkws-complete.min.js](mkws-complete.min.js))
 are always to the current versions of those
 files. Applications that rely on a particular version can
 instead use the specific numbered versions in
-<a href="releases/">the releases area</a>,
+[the releases area](releases/),
 for example
-<a href="releases/mkws-0.9.1.js">releases/mkws-0.9.1.js</a>.
+[releases/mkws-0.9.1.js](releases/mkws-0.9.1.js).
 
 The current version number is always in
-<a href="VERSION">the VERSION file</a>.
+[the VERSION file](VERSION).
 
 Version history is in
-<a href="NEWS">the NEWS file</a>.
+[the NEWS file](NEWS).
 
 Examples using the widget-set
 -----------------------------
@@ -153,80 +148,62 @@ are and how various things are done.
 
 ### Simple examples
 
-* A very simple application at
-  <a href="//example.indexdata.com/simple.html"
-       >//example.indexdata.com/simple.html</a>.
-* <a href="//example.indexdata.com/minimal.html"
-       >The absolutely minimal application</a>
+* A very simple application at <http://example.indexdata.com/simple.html>
+* [The absolutely minimal application](//example.indexdata.com/minimal.html)
   listed above.
-* <a href="//example.indexdata.com/language.html"
-       >A more detailed version</a>
+* [A more detailed version](//example.indexdata.com/language.html)
   that contains a configuration structure instead of accepting the
   defaults. Includes a custom translation option to present the
   application in Arabic.
-* <a href="//example.indexdata.com/mobile.html"
-       >A version suitable for mobile devices</a>,
+* [A version suitable for mobile devices](//example.indexdata.com/mobile.html)
   with a responsive design that moves components around depending on
   the screen size.
 
 ### Advanced examples
 
 * An application that
-  <a href="//example.indexdata.com/lowlevel.html"
-       >uses lower-level MKWS components</a>
+  [uses lower-level MKWS components](//example.indexdata.com/lowlevel.html)
   rather than the all-in-one `#mkwsResults` division,
   allowing it to use a rather different layout.
 * An application that specifies how to display brief and full records
-  <a href="//example.indexdata.com/templates.html"
-       >using Handlebar templates</a>.
+  [using Handlebar templates](//example.indexdata.com/templates.html).
   (Read about
-  <a href="http://handlebarsjs.com/"
-       >the templating language</a>.)
+  [the templating language](//handlebarsjs.com/).)
 * An application that
-  <a href="http://example.indexdata.com/images.html?q=portrait"
-       >displays thumbnail images</a>.
-* <a href="//example.indexdata.com/localauth.html"
-       >An application that uses a local authentication regime</a>,
+  [displays thumbnail images](//example.indexdata.com/images.html?q=portrait).
+* An application that
+  [uses a local authentication regime](//example.indexdata.com/localauth.html)
   and the corresponding
-  <a href="//example.indexdata.com/apache-config.txt"
-       >Apache2 configuration stanza</a>.
-* <a href="//example.indexdata.com/popup.html"
-       >A version that uses a jQuery popup</a>.
+  [Apache2 configuration stanza](//example.indexdata.com/apache-config.txt).
+* [A version that uses a jQuery popup](//example.indexdata.com/popup.html).
 
 ### Non-standard interfaces
 
-* <a href="//example.indexdata.com/dict.html"
-       >An application that uses MKWS to find dictionary
-  definitions of words when you highlight them</a>.
-* <a href="//example.indexdata.com/auto.html"
-       >An application that runs an automatic search on load</a>.
+* An application that uses MKWS to
+  [find dictionary definitions of words](//example.indexdata.com/dict.html)
+  when you highlight them.
+* An application that
+  [runs an automatic search on load](//example.indexdata.com/auto.html).  
 * An existing web-site,
-  <a href="http://sagp.miketaylor.org.uk/"
-       >The Self-Appointed Grammar Police</a>,
+  [The Self-Appointed Grammar Police](//sagp.miketaylor.org.uk/)
   which has been fitted with an MKWS searching widget.
   (See also the MKWS-widget customisations in
-  <a href="http://sagp.miketaylor.org.uk/style.css"
-       >that site's stylesheet</a>.)
-<!---
+  [that site's stylesheet](//sagp.miketaylor.org.uk/style.css).)
 * Another existing web-site,
-  <a href="http://zthes.z3950.org/"
-       >The Zthes specifications</a>,
+  [The Zthes specifications](//zthes.z3950.org/),
   which has been fitted with a popup MKWS search-box.
--->
 
 Target selection
 ----------------
 
 MKWS comes pre-configured to search in a set of a dozen or so
 open-access targets, as a proof of concept. But you'll want
-to use it to search your own selection of targets -- some open
-access, some subscription.
+to use it to
+[search your own selection of targets](mkws-manual.html#mkws-target-selection)
+-- some open access, some subscription.
 
-We can set that up for you: email us on
-<a href="mailto:info@indexdata.com"
-               >info@indexdata.com</a>.
+We can set that up for you: email us on <info@indexdata.com>.
 
 - - -
 
-Copyright (&copy;) 2013-2014 Index Data ApS.
-<a href="http://indexdata.com">`http://indexdata.com`</a>
+Copyright (&copy;) 2013-2014 Index Data ApS. <http://indexdata.com>