X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;h=1066f63fadbff802bb0157b2a2edaf04ee3b2944;hb=948c00ce0f5621e9fda178f24e053b4a608b5561;hp=62ab6255b5eedd6a5421315627ec93c9b79f84a3;hpb=83d22f2216e403a9eb3df3ddf9cb69fc2e43d061;p=mkws-moved-to-github.git
diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 62ab625..1066f63 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
@@ -882,8 +882,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)
-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.
@@ -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:
` 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