X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=d5332cb95ba1046e48ab2d5bf396120c18d64e62;hb=c209fd276576df2500e25299a00120db4c573884;hp=62ab6255b5eedd6a5421315627ec93c9b79f84a3;hpb=83d22f2216e403a9eb3df3ddf9cb69fc2e43d061;p=mkws-moved-to-github.git

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 62ab625..d5332cb 100644
--- 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
-% October 2014
+% November 2014
 
 
 Introduction
@@ -1155,9 +1155,9 @@ 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"
@@ -1179,107 +1179,113 @@ The properties of the `popup` widget are as follows:
 ----
 Element         Type    Default             Description
 --------        -----   -------             ------------
-popup_width     string  880                 Width of the popup window, in pixels.
+popup_width     int     880                 Width of the popup window, in pixels.
 
-popup_height    string  760                 Height of the popup window, 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.
 
 ----
 
 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
-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 )*
-
-	#mkwsSearch
-	  form
-	    input#mkwsQuery type=text
-	    input#mkwsButton type=submit
-
-	#mkwsBlanket
-	  (no contents -- used only for masking)
-
-	#mkwsResults
+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
+	
+	.mkws-search
+	  form.mkws-search-form
+	    input.mkws-query
+	    input.mkws-button
+	
+	.mkws-results
 	  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
-	#mkwsTargets
-	  #mkwsBytarget
-	    table
-	      thead
-	        tr*
-	          td*
-	      tbody
-	        tr*
-	          td*
-
-	#mkwsStat
-	  span.head
-	  span.clients
-	  span.records
-
+	      tr
+	        td
+	          div.mkws-facets-container-narrow
+	
+	.mkws-targets
+	  table
+	    thead
+	      tr
+	        td*
+	    tbody
+	      tr*
+	        td*
+	
 
 Appendix: compatibility roadmap
 ===============================
 
-FIXME: more to write here.
+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.
 
 
-Old and new-style class-names
------------------------------
+Major version 1.x
+-----------------
 
-**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`.
+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