From f3b0e5a1eaf5d1f1a58e48907b151cb469ff95c6 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Thu, 16 Oct 2014 14:28:32 +0100 Subject: [PATCH] Complete rewrite of index.html, up to date with present code. Clean up into proper Markdown. --- doc/index.markdown | 187 +++++++++++++++++++++++----------------------------- 1 file changed, 82 insertions(+), 105 deletions(-) diff --git a/doc/index.markdown b/doc/index.markdown index ee584db..bd152b0 100644 --- a/doc/index.markdown +++ b/doc/index.markdown @@ -1,6 +1,6 @@ % MKWS: the MasterKey Widget Set - +% 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 - so that very simple applications such as +`http://mkws.indexdata.com/` so that very simple applications such as can have MasterKey searching with minimal effort. All you need to do is pull in our JavaScript and optional stylesheet, then add `
`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)
@@ -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: - -~~~ - -~~~ + + +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 `
`s can be added (with no content), and will be filled in by MKWS: -* `
` -- switch between record and target views -* `
` -- switch between English, Danish and German -* `
` -- search box and button -* `
` -- result list, including pager/sorting -* `
` -- target list, including status -* `
` -- summary statistics +* `
` -- search box and button +* `
` -- result list, including pager/sorting +* `
` -- summary statistics +* `
` -- switch between record and target views +* `
` -- target list, including status +* `
` -- 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: - -~~~ - -~~~ - -For much more detail, see: -[Embedded metasearching with the MasterKey Widget Set](mkws-manual.html) - -Documentation -------------- - -* This file. - [PDF version] -* The MKWS manual, including a reference section. - [PDF version] -* The MKWS developers' guide. - [PDF version] - -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: + + + +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: -* mkws.js -- +* [mkws.js](mkws.js) -- JavaScript code that powers the MasterKey Widget Set -* pazpar2/js/pz2.js -- +* [pazpar2/js/pz2.js](pazpar2/js/pz2.js) -- Low-level JavaScript library for access to the MasterKey web service. -* handlebars-v2.0.0.js -- +* [handlebars-v2.0.0.js](handlebars-v2.0.0.js) -- A local copy of - the Handlebars templating library, + [the Handlebars templating library](//handlebarsjs.com/), since it doesn't like to be hotlinked. -* Local copy of jquery-1.10.0.min.js -* Local copy of jquery.json-2.4.js -* mkws-complete.js -- +* 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. -* mkws.css -- +* [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: -* mkws.min.js -* mkws-complete.min.js +* [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 -(mkws.js, -mkws-complete.js, -mkws.min.js +([mkws.js](mkws.js), +[mkws-complete.js](mkws-complete.js), +[mkws.min.js](mkws.min.js) and -mkws-complete.min.js) +[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 -the releases area, +[the releases area](releases/), for example -releases/mkws-0.9.1.js. +[releases/mkws-0.9.1.js](releases/mkws-0.9.1.js). The current version number is always in -the VERSION file. +[the VERSION file](VERSION). Version history is in -the NEWS file. +[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 - //example.indexdata.com/simple.html. -* The absolutely minimal application +* A very simple application at +* [The absolutely minimal application](//example.indexdata.com/minimal.html) listed above. -* A more detailed version +* [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 version suitable for mobile devices, +* [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 - uses lower-level MKWS components + [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 - using Handlebar templates. + [using Handlebar templates](//example.indexdata.com/templates.html). (Read about - the templating language.) + [the templating language](//handlebarsjs.com/).) * An application that - displays thumbnail images. -* An application that uses a local authentication regime, + [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 - Apache2 configuration stanza. -* A version that uses a jQuery popup. + [Apache2 configuration stanza](//example.indexdata.com/apache-config.txt). +* [A version that uses a jQuery popup](//example.indexdata.com/popup.html). ### Non-standard interfaces -* An application that uses MKWS to find dictionary - definitions of words when you highlight them. -* An application that runs an automatic search on load. +* 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, - The Self-Appointed Grammar Police, + [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 - that site's stylesheet.) - 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 -info@indexdata.com. +We can set that up for you: email us on . - - - -Copyright (©) 2013-2014 Index Data ApS. -`http://indexdata.com` +Copyright (©) 2013-2014 Index Data ApS. -- 1.7.10.4