Get rid of the responsive_design boolean configuration item, and always use responsiv...

[mkws-moved-to-github.git] / tools / htdocs / whitepaper.markdown

diff --git a/tools/htdocs/whitepaper.markdown b/tools/htdocs/whitepaper.markdown
index 8cf15fc..7a07fed 100644 (file)
--- a/tools/htdocs/whitepaper.markdown
+++ b/tools/htdocs/whitepaper.markdown
@@ -213,13 +213,11 @@ screen-width changes (as when a small device is rotated). To achieve
 this, MKWS supports responsive design which will move the termlists to
 the bottom on narrow screens and to the sidebar on wide screens.
 
 this, MKWS supports responsive design which will move the termlists to
 the bottom on narrow screens and to the sidebar on wide screens.
 

-To turn on this behaviour, set the `responsive_design` configuration
-element to `true`, and `responsive_design_width` to the desired
+To turn on this behaviour, set the `responsive_design_width` to the desired

 threshhold width in pixels. For example:
 
         <script type="text/javascript">
             var mkws_config = {
 threshhold width in pixels. For example:
 
         <script type="text/javascript">
             var mkws_config = {

-                responsive_design: true,

                 responsive_design_width: 990
             };
         </script>
                 responsive_design_width: 990
             };
         </script>

@@ -292,43 +290,34 @@ lang                     string  en        Code of the default language to displ
 lang_options             array   []        A list of the languages to offer as options. If empty (the default), then all
                                            configured languages are listed.
 
 lang_options             array   []        A list of the languages to offer as options. If empty (the default), then all
                                            configured languages are listed.
 

-show_lang                bool    true      Indicates whether or not to display the language menu. ### We should get rid of this
-                                           setting, and simply display the menu if there's an `mkwsLang` element.
+show_lang                bool    true      Indicates whether or not to display the language menu.

 
 language_*               hash              Support for any number of languages can be added by providing entries whose name is
                                            `language_` followed by the code of the language. See the separate section below for
                                            details.
 
 
 language_*               hash              Support for any number of languages can be added by providing entries whose name is
                                            `language_` followed by the code of the language. See the separate section below for
                                            details.
 

-pazpar2_url              string  *Note 2*  The URL used to access the metasearch middleware if `use_service_proxy` is false. ###
-                                           It's silly that you have to provide a different setting depending on whether
-                                           `use_service_proxy` is set. Should just use pazpar2_url in all cases.
+pazpar2_url              string  *Note 2*  The URL used to access the metasearch middleware. This service must be configured to
+                                           provide search results, facets, etc. It may be either unmediated or Pazpar2 the
+                                           MasterKey Service Proxy, which mediates access to an underlying Pazpar2 instance. In
+                                           the latter case, `service_proxy_auth` must be provided.

 
 perpage_options          array   *Note 3*  A list of candidate page sizes. Users can choose between these to determine how many
                                            records are displayed on each page of results.
 
 
 perpage_options          array   *Note 3*  A list of candidate page sizes. Users can choose between these to determine how many
                                            records are displayed on each page of results.
 

-perpage_default          string  20        The initial value for the number of records to show on each page. ### The `perpage` and
-                                           `perpage_default` entries should be renamed `perpage_display` and `perpage`
-                                           respectively for consistency with the language-related settings.
+perpage_default          string  20        The initial value for the number of records to show on each page.

 
 

-show_perpage             bool    true      Indicates whether or not to display the perpage menu. ### We should get rid of this
-                                           setting, and simply display the menu if an appropriate container is provided.
+show_perpage             bool    true      Indicates whether or not to display the perpage menu.

 
 query_width              int     50        The width of the query box, in characters.
 
 
 query_width              int     50        The width of the query box, in characters.
 

-responsive_design        bool    false     If true, then the facets display moves between two locations as the screen-width
-                                           varies, as described above. ### This entry should not exist: the design should be
-                                           responsive whenever `responsive_design_width` has a defined value.
-
-responsive_design_width  int     980       If `responsive_design` is true, this is the threshhold width, in pixels, at which the
-                                           facets move between their two locations.
+responsive_design_width  int               If defined, then the facets display moves between two locations as the screen-width
+                                           varies, as described above. The specified number is the threshhold width, in pixels,
+                                           at which the facets move between their two locations.

 
 service_proxy_auth       url     *Note 4*  A 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.
 
 
 service_proxy_auth       url     *Note 4*  A 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.
 

-service_proxy_url        string  *Note 5*  The URL on which the service proxy is accessed if `use_service_proxy` is true. This
-                                           service must be configured to provide search results, facets, etc.
-

 sort_options             array   *Note 6*  List of supported sort criteria. Each element of the list is itself a two-element list:
                                            the first element of each sublist is a pazpar2 sort-expression such as `data:0` and
                                            the second is a human-readable label such as `newest`.
 sort_options             array   *Note 6*  List of supported sort criteria. Each element of the list is itself a two-element list:
                                            the first element of each sublist is a pazpar2 sort-expression such as `data:0` and
                                            the second is a human-readable label such as `newest`.

@@ -336,8 +325,7 @@ sort_options             array   *Note 6*  List of supported sort criteria. Each
 sort_default             string  relevance The label of the default sort criterion to use. Must be one of those in the `sort`
                                            array.
 
 sort_default             string  relevance The label of the default sort criterion to use. Must be one of those in the `sort`
                                            array.
 

-show_sort                bool    true      Indicates whether or not to display the sort menu. ### We should get rid of this
-                                           setting, and simply display the menu if an appropriate container is provided.
+show_sort                bool    true      Indicates whether or not to display the sort menu.

 
 use_service_proxy        bool    true      If true, then a Service Proxy is used to deliver searching services rather than raw
                                            Pazpar2. ### Do we even need this? Can't we just assume that the Service Proxy is in
 
 use_service_proxy        bool    true      If true, then a Service Proxy is used to deliver searching services rather than raw
                                            Pazpar2. ### Do we even need this? Can't we just assume that the Service Proxy is in

@@ -345,6 +333,13 @@ use_service_proxy        bool    true      If true, then a Service Proxy is used
                                            use the same entry to specify the URL in either case.
 ---
 
                                            use the same entry to specify the URL in either case.
 ---
 

+Perhaps we should get rid of the `show_lang`, `show_perpage` and
+`show_sort` configuration items, and simply display the relevant menus
+only when their containers are provided -- e.g. an `mkwsLang` element
+for the language menu. But for now we retain these, as an easier route
+to lightly customise the display than my changing providing a full HTML
+structure.
+

 #### Notes
 
 1. ["sources", "subjects", "authors"]
 #### Notes
 
 1. ["sources", "subjects", "authors"]