projects / mkws-moved-to-github.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Note on jsnlog.min.js -- thanks to Biligsaikhan Batjargal for pointing it out.
[mkws-moved-to-github.git] / doc / index.markdown
diff --git a/doc/index.markdown b/doc/index.markdown
index ee584db..64070b1 100644 (file)
--- a/doc/index.markdown
+++ b/doc/index.markdown
@@ -1,6 +1,6 @@
 % MKWS: the MasterKey Widget Set
 % MKWS: the MasterKey Widget Set
-<!---% Mike Taylor
-% June 2014-->
+% Mike Taylor
+% November 2014
 
 
 Add metasearching to your web-site painlessly
 
 
 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
 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
 <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
 -----------------
 
 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>
 
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
        <div class="mkwsSearch"></div>
@@ -48,102 +48,102 @@ else is refinement.
 Configuring a client (short version)
 ------------------------------------
 
 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:
 
 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>
        <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:
 
 
 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`
 
 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:
 
 
 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
   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.
   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 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.
   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)
+* Local copy of [jsnlog.min.js](jsnlog.min.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 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 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
 
 ### 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
 and
-<a href="mkws-complete.min.js">mkws-complete.min.js</a>)
+[mkws-complete.min.js](mkws-complete.min.js))
+together with the CSS file
+([mkws.css](mkws.css))
 are always to the current versions of those
 files. Applications that rely on a particular version can
 instead use the specific numbered versions in
 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
 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).
+and
+[releases/mkws-0.9.1.css](releases/mkws-0.9.1.css).
 
 The current version number is always in
 
 The current version number is always in
-<a href="VERSION">the VERSION file</a>.
+[the VERSION file](VERSION).
 
 Version history is in
 
 Version history is in
-<a href="NEWS">the NEWS file</a>.
+[the NEWS file](NEWS).
 
 Examples using the widget-set
 -----------------------------
 
 Examples using the widget-set
 -----------------------------
@@ -153,80 +153,57 @@ are and how various things are done.
 
 ### Simple examples
 
 
 ### 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.
   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.
   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
   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
   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
   (Read about
-  <a href="http://handlebarsjs.com/"
-       >the templating language</a>.)
+  [the templating language](//handlebarsjs.com/).)
+* An application that
+  [displays thumbnail images](//example.indexdata.com/images.html?q=portrait).
 * An application that
 * 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>,
+  [uses a local authentication regime](//example.indexdata.com/localauth.html)
   and the corresponding
   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?q=sushi).
 
 ### Non-standard interfaces
 
 
 ### 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 existing web-site,
-  <a href="http://sagp.miketaylor.org.uk/"
-       >The Self-Appointed Grammar Police</a>,
-  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>.)
-<!---
+* 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).  
 * Another existing web-site,
 * 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.
   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
 
 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 (C) 2013-2014 Index Data ApS. <http://indexdata.com>
MasterKey Widget Set