Fix very error-prone MarkDown table alignment.

[mkws-moved-to-github.git] / doc / mkws-manual.markdown

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 99513df..41fc31f 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -1,6 +1,6 @@
 % The MKWS manual: embedded metasearching with the MasterKey Widget Set
 % Mike Taylor
 % The MKWS manual: embedded metasearching with the MasterKey Widget Set
 % Mike Taylor

-% October 2014
+% November 2014

 
 
 Introduction
 
 
 Introduction

@@ -41,7 +41,7 @@ flexibility against convenience:
   [Drupal](https://www.drupal.org/)
   sites.
 
   [Drupal](https://www.drupal.org/)
   sites.
 

-All of these approaches require programming to a greater or lesser
+All but the last of these approaches require programming to a greater or lesser

 extent. Against this backdrop, we introduced
 [MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
 -- a set of simple, very high-level HTML+CSS+JavaScript
 extent. Against this backdrop, we introduced
 [MKWS (the MasterKey Widget Set)](http://mkws.indexdata.com/)
 -- a set of simple, very high-level HTML+CSS+JavaScript

@@ -171,22 +171,6 @@ is part of the `aux` team.
 Widgets that do not have a team specified (as in the examples above)
 are placed in the team called `AUTO`.
 
 Widgets that do not have a team specified (as in the examples above)
 are placed in the team called `AUTO`.
 

-Old and new-style class-names
------------------------------
-
-**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
-without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
-used to specify team names used an `mkwsTeam_` prefix (with an
-underscore). So instead of `mkws-team-foo`, it used to be
-`mkwsTeam_foo`.
-
-The 1.x series of MKWS releases recognise these old-style class-names
-as well as the canonical ones, as a facility for backwards
-compatibility. However, **these old class-names are deprecated, and
-support will be removed in v2.0**. Existing applications that use them
-should be upgraded to the new-style class names as soon as convenient.
-

 Configuring widgets
 ===================
 
 Configuring widgets
 ===================
 

@@ -558,7 +542,7 @@ its own User Access record.
 
 When credential-based authentication is in use (username and
 password), it's necessary to pass these credentials into the Service
 
 When credential-based authentication is in use (username and
 password), it's necessary to pass these credentials into the Service

-Proxy when establishing the session. This is done 
+Proxy when establishing the session. This is done

 by providing the `sp_auth_credentials` configuration setting as a string
 containing the username and password separated by a slash:
 
 by providing the `sp_auth_credentials` configuration setting as a string
 containing the username and password separated by a slash:
 

@@ -836,6 +820,11 @@ Name              Description
                   found for the current search, any diagnostics they
                   have returned, the number of records that have been
                   returned for display, and the connection state.
                   found for the current search, any diagnostics they
                   have returned, the number of records that have been
                   returned for display, and the connection state.

+
+`waiting`         An image, defaulting to <http://mkws.indexdata.com/progress.gif> unless overridden with the `src` configuration
+                  item, which is initially invisible, appears when a search is submitted, and disappears when the search is
+                  complete.
+

 ----
 
 
 ----
 
 

@@ -856,13 +845,8 @@ the relevant widgets are listed. All entries are optional, but if specified must
 default values are in footnotes to keep the table reasonably narrow.
 
 ----
 default values are in footnotes to keep the table reasonably narrow.
 
 ----

-Element                   Widget    Type    Default   Description
+Setting                   Widget    Type    Default   Description

 --------                  ------    -----   --------- ------------
 --------                  ------    -----   --------- ------------

-auth_hostname             _global_  string            If provided, overrides the `pp2_hostname` setting when constructing the
-                                                      Service Proxy authentication URL. This need only be used when authentication
-                                                      is performed on a different host from the remaining operations (search,
-                                                      retrieve, etc.)
-

 autosearch                facet,    string            If provided, this setting contains a query which is immediately run on behalf
                           facets,                     of the team. Often used with an [indirect setting](#indirect-settings).
                           record,
 autosearch                facet,    string            If provided, this setting contains a query which is immediately run on behalf
                           facets,                     of the team. Often used with an [indirect setting](#indirect-settings).
                           record,

@@ -886,7 +870,13 @@ facet_max_*               facet     int               Specifies how many terms a
 
 facets                    _team_    array   *Note 1*  Ordered list of names of facets to display.
 
 
 facets                    _team_    array   *Note 1*  Ordered list of names of facets to display.
 

-lang                      _team_    string            Two-letter ISO code of the default language to display the UI in. Supported
+freeze_opacity            records   float             If defined, a fractional value between in the range 0.0 (transparent) to 1.0
+                                                      (opaque). During the short period after a mouse-move over the records when
+                                                      the display will not be updated, the widget is faded to that opacity
+                                                      (reverting to full opacity when the period elapses or the mouse leaves the
+                                                      area).
+
+lang                      _team_    string            The code of the default language to display the UI in. Supported

                                                       language codes are `en` = English, `de` = German, `da` = Danish, and whatever
                                                       additional languages are configured using `language_*` entries (see below).
 
                                                       language codes are `en` = English, `de` = German, `da` = Danish, and whatever
                                                       additional languages are configured using `language_*` entries (see below).
 

@@ -903,8 +893,8 @@ limit                     facet,    string            Allows a partial search to
                           records,                    chapter of the Pazpar2 manual
                           results                     ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
 
                           records,                    chapter of the Pazpar2 manual
                           results                     ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
 

-log_level                 _global_  int     1         Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
-                                                      datestamps, 3 = messages with datestamps and stack-traces.
+log_level                 _global_  string  info      The lowest level of logging output to emit. Acceptable values are
+                                                      `trace`, `debug`, `info`, `warn`, `error` and `fatal`.

 
 maxrecs                   facet,    int               Limits the metasearching middleware to retrieving no more than the specified
                           facets,                     number of records from each target.
 
 maxrecs                   facet,    int               Limits the metasearching middleware to retrieving no more than the specified
                           facets,                     number of records from each target.

@@ -912,6 +902,10 @@ maxrecs                   facet,    int               Limits the metasearching m
                           records,
                           results
 
                           records,
                           results
 

+newsearch_opacity         records,  float             If defined, a fractional value between in the range 0.0 (transparent) to 1.0
+                          facets                      (opaque). When a new search is submitted, the widget fades to that opacity
+                                                      (reverting to full opacity when data arrives).
+

 paragraphs                reference int               Limits the number of paragraphs rendered to the specified number. If
                                                       omitted, there is no limit.
 
 paragraphs                reference int               Limits the number of paragraphs rendered to the specified number. If
                                                       omitted, there is no limit.
 

@@ -943,11 +937,6 @@ pp2_path                  _global_  string  *Note 4*  Unless overridden by the `
                                                       Proxy). Set this to connect to a service on a different host from the
                                                       default.
 
                                                       Proxy). Set this to connect to a service on a different host from the
                                                       default.
 

-responsive_design_width   _global_  int               If defined, then the facets display moves between two locations as the
-                                                      screen-width varies. The specified number is the threshhold width, in
-                                                      pixels, at which the facets move between their two locations. The `switch`
-                                                      and `lang` widgets also disappear entirely below this threshhold.
-

 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
                                                       widgets. If set to true, a different approach is used which may be faster
                                                       under some circumstances.
 scan_all_nodes            _global_  bool    false     An internal setting that changes how MKWS scans the HTML documen to discover
                                                       widgets. If set to true, a different approach is used which may be faster
                                                       under some circumstances.

@@ -958,8 +947,8 @@ sentences                 reference int               Limits the number of sente
 service_proxy_auth        _global_  url               If defined, this is the URL which, when `use_service_proxy` is true, is
                                                       fetched once at the beginning of each session to authenticate the user and
                                                       establish a session that encompasses a defined set of targets to search
 service_proxy_auth        _global_  url               If defined, this is the URL which, when `use_service_proxy` is true, is
                                                       fetched once at the beginning of each session to authenticate the user and
                                                       establish a session that encompasses a defined set of targets to search

-                                                      in. When not defined, the URL is assembled from `auth_hostname` or
-                                                      `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and
+                                                      in. When not defined, the URL is assembled from `sp_auth_hostname` or
+                                                      `pp2_hostname`, `pp2_path` or `sp_auth_path`, `sp_auth_query` and

                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       `sp_auth_credentials`. See the [Assembling Pazpar2
                                                       URLs](#assembling-pazpar2-urls) section below.
 

@@ -968,13 +957,13 @@ service_proxy_auth_domain _global_  domain            When the server used for a
                                                       the domain of the server that it proxies for, so that cookies are rewritten
                                                       to appear to be from this domain.
 
                                                       the domain of the server that it proxies for, so that cookies are rewritten
                                                       to appear to be from this domain.
 

-show_lang                lang       bool    true      Indicates whether or not to display the language menu.
+show_lang                 lang      bool    true      Indicates whether or not to display the language menu.

 
 

-show_perpage             ranking    bool    true      Indicates whether or not to display the perpage menu.
+show_perpage              ranking   bool    true      Indicates whether or not to display the perpage menu.

 
 

-show_sort                ranking    bool    true      Indicates whether or not to display the sort menu.
+show_sort                 ranking   bool    true      Indicates whether or not to display the sort menu.

 
 

-show_switch              switch     bool    true      Indicates whether or not to display the switch menu.
+show_switch               switch    bool    true      Indicates whether or not to display the switch menu.

 
 sort                      facet,    string            Specifies the order in which to sort the records retrieved by an
                           facets,                     auto-executing widget. Must be one of those in the `sort_options`
 
 sort                      facet,    string            Specifies the order in which to sort the records retrieved by an
                           facets,                     auto-executing widget. Must be one of those in the `sort_options`

@@ -995,12 +984,20 @@ sp_auth_credentials       _global_  string            If defined, this must be a
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 

-sp_auth_path              _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_hostname          _global_  string            If provided, overrides the `pp2_hostname` setting when constructing the
+                                                      Service Proxy authentication URL. This need only be used when authentication
+                                                      is performed on a different host from the remaining operations (search,
+                                                      retrieve, etc.)
+
+sp_auth_path              _global_  string            Part of the URL used for authentication. See the [Assembling Pazpar2

                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       URLs](#assembling-pazpar2-urls) section below.
 

-sp_auth_query             _global_  string  *Note 7*  Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_query             _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2

                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       URLs](#assembling-pazpar2-urls) section below.
 

+src                       waiting   url               The address of an image to use in the `waiting` widget in place of the
+                                                      default spinning wheel. Used to indicate that a search is in progress.
+

 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
                           record,                     section above.
 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See
                           facets,                     the [Choosing targets from the library](#choosing-targets-from-the-library)
                           record,                     section above.

@@ -1037,8 +1034,6 @@ template                  details,  string            Numerous widgets use Handl
                           switch,
                           targets
 
                           switch,
                           targets
 

-<!--- The widget called "record" is a special-case of "records"; both also use "summary" -->
-

 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
 text                      builder   string  "Build!"  Specifies what text to use for the Builder button.
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather

@@ -1057,26 +1052,52 @@ customise the display than by providing a full HTML structure.
 
 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
 
 
 3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`
 

-4. The default for `pp2_path` is `"service-proxy"`
+4. The default for `pp2_path` is `"service-proxy/"`

 
 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
 
 
 5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`
 

-6. The default for `sp_auth_path` is `"service-proxy/"`.
-
-7. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+6. The default for `sp_auth_query` is `"command=auth&action=perconfig"`

 
 ### Indirect settings
 
 The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for
 
 ### Indirect settings
 
 The values of any setting are generally interpreted literally. However, it is possible to specify a value indirectly -- for

-example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch query. FIXME
-say more.
+example, by reference to a query parameter -- and this is often useful in contexts such as specifying an autosearch
+query. Settings of this kind have values beginning with an exclamation mark, and take the form `!`_type_`!`_value_.
+
+The currently supported types are:

 
 

-FIXME !query!q, !path!2, etc.
+* `param` -- uses the value of the specified query parameter for the URL. For example
+`<div class="mkws-results" autosearch="!param!term">` will auto-search for the word "sushi" if the page containing that widget is
+invoked from the URL `http://example.com/magic/example.html?term=sushi`
+
+* `path` -- uses the value of the _n_th component of the URL path, as specified by the value. For example
+`!path!3` will auto-search for the word "dinosaur" if the page containing that widget is
+invoked from the URL `http://example.com/magic/lookup/dinosaur`
+
+* `var` -- uses the value of the named JavaScript global variable. This is a very powerful and general mechanism. For example, to
+  search for the reversed value of the query parameter called `reverseTerm`, you might write a JavaScript function to do the
+  extraction and reversing, the use the HTML:
+
+<!--- Due to a bug in pandoc, we need this comment to force the following code-block to be recognised -->
+
+               <script>var _reversedParam = extractAndReverse("term");</script>
+               <div class="mkws-results" autosearch="!var!_reversedParam">

 
 ### Assembling Pazpar2 URLs
 
 
 ### Assembling Pazpar2 URLs
 

-FIXME describe how `pazpar2_url` is assembled from `pp2_hostname` and `pp2_path`; and how `service_proxy_auth` is assembled from
-`auth_hostname` or `pp2_hostname`, `sp_auth_path`, `sp_auth_query` and `sp_auth_credentials`.
+Most of MKWS's functionality is achieved by use of the Pazpar2 middleware. This is accessed on an endpoint URL which is usually
+assembled from the two configuration sessings `pp2_hostname` and `pp2_path`. However, if for some reason an unusual Pazpar2
+endpoint must be used, that endpoint can be specified in the `pazpar2_url` setting, and that will be used instead.
+
+In the common case where Pazpar2 is accessed via the Service Proxy, an authentication call is made during initialisation. The call
+is generally made to the same endpoint as the other requests. However, the hostname used for authentication may if necessary be
+overridden using the `sp_auth_hostname` setting, and the path overridden by `sp_auth_path`. In any case, the value of
+`sp_auth_query` is appended; and if `sp_auth_credentials` is set, then it is used to add username and password parameters.
+
+So in the absence of any configuration added by an application, the Service Proxy authentication URL is made up of `pp2_hostname`
+(sp-mkws.indexdata.com) since `sp_auth_hostname` is undefined; and `pp2_path` (service-proxy/) since `sp_auth_path` is undefined;
+and `sp_auth_query` (command=auth&action=perconfig); and no credentials, since `sp_auth_credentials` is undefined. Therefore the
+URL `http://sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig` is generated.

 
 Language specification
 ----------------------
 
 Language specification
 ----------------------

@@ -1097,46 +1118,64 @@ in the specified language. For example:
        }
 
 The following strings occurring in the UI can be translated:
        }
 
 The following strings occurring in the UI can be translated:

-`Displaying`,
-`Next`,
-`Prev`,
-`Records`,
-`Search`,
-`Sort by`,
-`Targets`,
-`Facets`,
-`and show`,
-`found`,
-`of`,
-`per page`
-and
-`to`.
+
+* `Search complete: found`
+* `records`
+* `Displaying`
+* `to`
+* `of`
+* `found`
+* `Prev`
+* `Next`
+* `Sort by`
+* `and show`
+* `per page`
+* `Search`
+* `Active clients`
+* `Retrieved records`
+* `Records`
+* `Targets`
+* `Target ID`
+* `Hits`
+* `Diags`
+* `Records`
+* `State`

 
 In addition, facet names can be translated:
 
 In addition, facet names can be translated:

-`Authors`,
-`Sources`
-and
-`Subjects`.
+
+* `Authors`
+* `Sources`
+* `Subjects`
+
+and whatever field captions are defined by `facet_caption_*` settings.
+
+And sort-orders:
+
+* `relevance`
+* `title`
+* `newest`
+* `oldest`
+
+and whatever sort-orders are defined by the `sort_options` setting.

 
 Finally, the names of fields in the full-record display can be
 translated. These include, but may not be limited to:
 
 Finally, the names of fields in the full-record display can be
 translated. These include, but may not be limited to:

-`Author`,
-`Date`,
-`Location`,
-`Subject`
-and
-`Title`.
-

 
 

+* `Title`
+* `Date`
+* `Author`
+* `Links`
+* `Subject`
+* `Locations`

 
 jQuery UI popup invocation
 --------------------------
 
 The MasterKey Widget Set can be invoked in a popup window on top of the page.
 
 
 jQuery UI popup invocation
 --------------------------
 
 The MasterKey Widget Set can be invoked in a popup window on top of the page.
 

-Note that when using the `popup` layout, facilities from the jQuery UI
-toolkit are used, so it's necessary to include both CSS and JavaScript
-from that toolkit. The relevant lines are:
+Note that the `popup` widget uses facilities from the jQuery UI, so
+it's necessary to include both CSS and JavaScript from that
+toolkit. The relevant lines are:

 
        <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
        <link rel="stylesheet" type="text/css"
 
        <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
        <link rel="stylesheet" type="text/css"

@@ -1151,96 +1190,127 @@ from that toolkit. The relevant lines are:
          <div class="mkws-stat"></div>
        </div>
 
          <div class="mkws-stat"></div>
        </div>
 

+Popup windows can contain any HTML, not just MKWS widgets.
+
+The properties of the `popup` widget are as follows:
+

 ----
 ----

-Element         Type    Default             Description
+Setting         Type    Default             Description

 --------        -----   -------             ------------
 --------        -----   -------             ------------

-popup_width     string  880                 Width of the popup window (if used), in
-                                            pixels.
+popup_width     int     880                 Width of the popup window, in pixels.

 
 

-popup_height    string  760                 Height of the popup window (if used), in
-                                            pixels.
+popup_height    int     760                 Height of the popup window, in pixels.

 
 

-popup_button    string  `input.mkwsButton`  A click on this selector will trigger the
-                                           popup to open
+popup_button    string  `input.mkwsButton`  A jQuery selector identifying the element which, which clicked, pops up the window.

 
 

-popup_modal     string  0                   Modal confirmation mode. Valid values are 0 or 1
+popup_modal     bool    0                   Indicates whether the popup is modal (blocks access to the background page until
+                                            dismissed). Set to 1 if a modal popup is required.

 
 

-popup_autoOpen  string  1                   Open popup window on load. Valid values are 0 or 1
+popup_autoOpen  bool    1                   Indictaes whether to pop up the window automatically when the page is loaded.

 
 ----
 
 
 ----
 

-You can have more than one mkws-popup widgets on a page. Please use a different 
-popup_button value to address the right ones.
+Multiple `popup` widgets can co-exist on a page. In this case, different
+`popup_button` values must be used for each.

 
 

-The structure of the HTML generated by the MKWS widgets
--------------------------------------------------------
+Structure of HTML generated by widgets
+--------------------------------------

 
 In order to override the default CSS styles provided by the MasterKey Widget
 
 In order to override the default CSS styles provided by the MasterKey Widget

-Set, it's necessary to understand that structure of the HTML elements that are
-generated within the widgets. This knowledge make it possible, for example,
-to style each `<div>` with class `term` but only when it occurs inside an
-element with class `mkws-facets`, so as to avoid inadvertently styling other
-elements using the same class in the non-MKWS parts of the page.
-
-The HTML structure is as follows. As in CSS, #ID indicates a unique identifier
-and .CLASS indicates an instance of a class.
-
-       #mkwsSwitch
-         a*
-       
-       #mkwsLang
-         ( a | span )*
+Set, it's necessary to understand the structure of the HTML elements that are
+generated within the widgets. The HTML structure is as follows. As in CSS,
+_.class_ indicates an instance of a class. A trailing `*` indicates zero or
+more instances; a trailing `?` indicates zero or one instance.
+
+       .mkws-progress
+         span.mkws-done
+         span.mkws-waiting

        
        

-       #mkwsSearch
-         form
-           input#mkwsQuery type=text
-           input#mkwsButton type=submit
+       .mkws-search
+         form.mkws-search-form
+           input.mkws-query
+           input.mkws-button

        
        

-       #mkwsBlanket
-         (no contents -- used only for masking)
-       
-       #mkwsResults
+       .mkws-results

          table
            tbody
              tr
          table
            tbody
              tr

-               td
-                 #mkwsTermlists
-                   div.title
-                   div.facet*
-                     div.termtitle
-                     ( a span br )*
-               td
-                 div#mkwsRanking
-                   form#mkwsSelect
-                     select#mkwsSort
-                     select#mkwsPerpage
-                 #mkwsPager
-                 #mkwsNavi
-                 #mkwsRecords
-                   div.record*
-                     span (for sequence number)
-                     a (for title)
-                     span (for other information such as author)
-                     div.details (sometimes)
+               td.mkws-facets-container-wide
+                 div.mkws-facets
+                   div.mkws-facet*
+                     div.mkws-facet-title
+                     div.mkws-term*
+                       a
+                       span
+               td.mkws-motd-container
+                 div.mkws-ranking
+                   form
+                     select.mkws-sort
+                       option*
+                     select.mkws-perpage
+                       option*
+                 div.mkws-pager
+                   div
+                   div
+                     span.mkws-prev
+                     span.mkws-current-page
+                     a*
+                     span.mkws-next
+                 div.mkws-navi
+                 div.mkws-records
+                   div.mkws-summary*
+                     div.mkws-field-data
+                       span.mkws-field-NAME*
+                     div.mkws-details?

                        table
                          tbody
                            tr*
                              th
                              td
                        table
                          tbody
                            tr*
                              th
                              td

-       #mkwsTargets
-         #mkwsBytarget
-           table
-             thead
-               tr*
-                 td*
-             tbody
-               tr*
-                 td*
+             tr
+               td
+                 div.mkws-facets-container-narrow
+       
+       .mkws-targets
+         table
+           thead
+             tr
+               td*
+           tbody
+             tr*
+               td*

        
        

-       #mkwsStat
-         span.head
-         span.clients
-         span.records
+
+Appendix: compatibility roadmap
+===============================
+
+Wherever possible, we ensure that all functional changes in MKWS are
+backwards-compatible, so that applications written against old versions of the
+toolkit will continue to work when running against newer versions.
+
+However, a few aspects of functionality unavoidably change in backwards
+incompatible ways. We ensure that **this only happens with new major
+versions** -- so it should _always_ be safe to upgrade to a new minor version.
+As an aid to porting old applications, we here note the specific
+backwards-incompatible changes in the various major releases, and those
+planned for future major releases.
+
+
+Major version 1.x
+-----------------
+
+Versions of MKWS before v1.0 (including the only prior release, v0.9.1) used
+camel-case class-names: without hyphens and with second and subsequent words
+capitalised. So instead of `mkws-search`, it used to be `mkwsSearch`. And the
+classes used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be `mkwsTeam_foo`.
+
+The 1.x series of MKWS releases recognise these old-style class-names
+as well as the canonical ones, as a facility for backwards
+compatibility. However, **these old class-names are deprecated, and
+support will be removed in v2.0**. Existing applications that use them
+should be upgraded to the new-style class names as soon as convenient.
+

 
 - - -
 
 
 - - -