Remove mentions of responsive_design_width, which is kinda deprecated.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 05a46ea..78d1a49 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -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
 ===================
 

@@ -202,16 +186,14 @@ like this:
            lang_options: [ "en", "da" ]
            lang: "da",
            sort_default: "title",
            lang_options: [ "en", "da" ]
            lang: "da",
            sort_default: "title",

-           query_width: 60

          };
        </script>
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
 This configuration restricts the set of available UI languages English
 and Danish (omitting German), sets the default to Danish (rather than
          };
        </script>
        <script type="text/javascript" src="http://mkws.indexdata.com/mkws-complete.js"></script>
 
 This configuration restricts the set of available UI languages English
 and Danish (omitting German), sets the default to Danish (rather than

-the English), initially sorts search results by title rather than
-relevance (though as always this can be changed in the UI) and makes
-the search box a bit wider than the default.
+the English), and initially sorts search results by title rather than
+relevance (though as always this can be changed in the UI).

 
 The full set of supported configuration settings is described in the
 reference guide below.
 
 The full set of supported configuration settings is described in the
 reference guide below.

@@ -945,13 +927,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.
 

-query_width               _search_  int     50        The width of the query box, in characters.
-
-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.

@@ -1049,12 +1024,9 @@ use_service_proxy         _global_  bool    true      If true, then a Service Pr
                                                       than raw Pazpar2. An authentication phase is run during initialisation.
 ----
 
                                                       than raw Pazpar2. An authentication phase is run during initialisation.
 ----
 

-(Perhaps we should get rid of the `show_lang`, `show_perpage`,
-`show_sort` and `show_switch` configuration settings, as we display the relevant menus
-only when their containers are provided -- e.g. an `mkws-lang` element
-for the language menu. But for now we retain these, as an easier route
-to lightly customise the display than by providing a full HTML
-structure.)
+The `show_lang`, `show_perpage`, `show_sort` and `show_switch` configuration settings are technically redundant, as the relevant
+widgets, like all widgets, are displayed only when they are provided. But they are retained as an easier route to lightly
+customise the display than by providing a full HTML structure.

 
 ### Notes
 
 
 ### Notes
 

@@ -1074,6 +1046,10 @@ structure.)
 
 ### Indirect settings
 
 
 ### 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.
+

 FIXME !query!q, !path!2, etc.
 
 ### Assembling Pazpar2 URLs
 FIXME !query!q, !path!2, etc.
 
 ### Assembling Pazpar2 URLs

@@ -1245,6 +1221,30 @@ and .CLASS indicates an instance of a class.
          span.clients
          span.records
 
          span.clients
          span.records
 

+
+Appendix: compatibility roadmap
+===============================
+
+FIXME: more to write here.
+
+
+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.
+
+

 - - -
 
 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>
 - - -
 
 Copyright (C) 2013-2014 Index Data ApS. <http://indexdata.com>