Tweak.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 184bb98..c868b5a 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -871,18 +871,26 @@ autosearch                facet,    string            If provided, this setting
                           records,
                           results
 
                           records,
                           results
 

-facet                     facet     string
+facet                     facet     string            For a `facet` widget, this setting is mandatory, and indicates which field to
+                                                      list terms for. Three fields are supported: `subject`, `author` and
+                                                      `xtargets` -- the latter a special case which treats the target providing a
+                                                      record as a facet. Any other field may also be used, but the default caption
+                                                      and maximum term-count may not be appropriate, needing to be overridden by
+                                                      `facet_caption_*` and `facet_max_*` settings.

 
 

-facet_caption_*           facet     string
+facet_caption_*           facet     string            Specifies what on-screen caption is to be used for the named facet: for
+                                                      example, if a `date` facet is generated, then `facet_caption_date` can be
+                                                      used to set the caption to "Year".

 
 

-facet_max_*               facet     int
+facet_max_*               facet     int               Specifies how many terms are to be displayed for the named facet: for
+                                                      example, if a `publisher` facet is generated, then `facet_max_publisher` can
+                                                      be used to limit the list to the top six.

 
 

-facets                    _team_    array   *Note 1*  Ordered list of names of facets to display. Supported facet names are
-                                                      `xtargets`, `subject` and `author`.
+facets                    _team_    array   *Note 1*  Ordered list of names of facets to display.

 
 

-lang                      _team_    string  en        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).
+lang                      _team_    string            Two-letter ISO 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).

 
 lang_options              lang      array   []        A list of the languages to offer as options. If empty (the default), then all
                                                       configured languages are listed.
 
 lang_options              lang      array   []        A list of the languages to offer as options. If empty (the default), then all
                                                       configured languages are listed.

@@ -891,63 +899,78 @@ language_*                _global_  hash              Support for any number of
                                                       name is `language_` followed by the code of the language. See the separate
                                                       section below for details.
 
                                                       name is `language_` followed by the code of the language. See the separate
                                                       section below for details.
 

-limit                     facet,    string            ### See the Search section in
-                          facets,                     [the Protocol chapter of the Pazpar2 manual
-                          record,                     ](http://www.indexdata.com/pazpar2/doc/pazpar2_protocol.html)
-                          records,
-                          results
+limit                     facet,    string            Allows a partial search to be included in the specification of an
+                          facets,                     auto-executing widget. This is ANDed with the submitted query, as though it
+                          record,                     had been selected from a facet. See the Search section in [the Protocol
+                          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_  int     1         Level of debugging output to emit. 0 = none, 1 = messages, 2 = messages with
                                                       datestamps, 3 = messages with datestamps and stack-traces.
 

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

                           record,
                           records,
                           results
 
                           record,
                           records,
                           results
 

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

 
 

-pazpar2_url               _global_  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.
+pazpar2_url               _global_  string            If specified, this is the URL used to access the metasearch middleware. This
+                                                      service must be configured to provide search results, facets, etc. It may be
+                                                      either unmediated Pazpar2 or the MasterKey Service Proxy, which mediates
+                                                      access to an underlying Pazpar2 instance. When not specified, the URL is
+                                                      assembled from `pp2_hostname` and `pp2_path`. See the [Assembling Pazpar2
+                                                      URLs](#assembling-pazpar2-urls) section below.

 
 

-perpage                   facet,    int
-                          facets,
-                          record,
+perpage                   facet,    int               Specifies the number of records to show per page in an auto-executing
+                          facets,                     widget. Contrast with `perpage_default`, which is used to prime the dropdown
+                          record,                     with which a user chooses the page-size in an interactive session.

                           records,
                           results
 
 perpage_default           _team_    string  20        The initial value for the number of records to show on each page.
 
                           records,
                           results
 
 perpage_default           _team_    string  20        The initial value for the number of records to show on each page.
 

-perpage_options           ranking   array   *Note 3*  A list of candidate page sizes. Users can choose between these to determine
+perpage_options           ranking   array   *Note 2*  A list of candidate page sizes. Users can choose between these to determine

                                                       how many records are displayed on each page of results.
 
                                                       how many records are displayed on each page of results.
 

-pp2_hostname              _global_  string
+pp2_hostname              _global_  string  *Note 3*  Unless overridden by the `pazpar2_url` setting, this is used together with
+                                                      `pp2_path` to construct the URL to the Pazpar2 service (or Service
+                                                      Proxy). Set this to connect to a service on a different host from the
+                                                      default.

 
 

-pp2_path                  _global_  string
+pp2_path                  _global_  string  *Note 4*  Unless overridden by the `pazpar2_url` setting, this is used together with
+                                                      `pp2_hostname` to construct the URL to the Pazpar2 service (or Service
+                                                      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
 
 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, as described above. The specified number is the
-                                                      threshhold width, in pixels, at which the facets move between their two
-                                                      locations.
-
-scan_all_nodes            _global_  bool
-
-sentences                 reference int
-
-service_proxy_auth        _global_  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_domain _global_  domain            Can be set to the domain for which `service_proxy_auth` proxies
-                                                      authentication, so that cookies are rewritten to appear to be from this
-                                                      domain. In general, this is not necessary, as this setting defaults to the
-                                                      domain of `pazpar2_url`.
+                                                      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.
+
+sentences                 reference int               Limits the number of sentences rendered to the specified number. If
+                                                      omitted, there is no limit.
+
+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
+                                                      `sp_auth_credentials`. See the [Assembling Pazpar2
+                                                      URLs](#assembling-pazpar2-urls) section below.
+
+service_proxy_auth_domain _global_  domain            When the server used for authentication -- e.g. the one identified by the
+                                                      `service_proxy_auth` URL -- proxies for different server, this can be set to
+                                                      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.
 

@@ -955,58 +978,61 @@ show_perpage             ranking    bool    true      Indicates whether or not t
 
 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, for switching between
-                                                      showing retrieved records and target information.
+show_switch              switch     bool    true      Indicates whether or not to display the switch menu.

 
 

-sort                      facet,    string
-                          facets,
-                          record,
-                          records,
+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`
+                          record,                     array. Contrast with `sort_default`, which is used to prime the dropdown
+                          records,                    with which a user chooses the sortorder in an interactive session.

                           results
 
                           results
 

-sort_default              _team_    string  relevance The label of the default sort criterion to use. Must be one of those in the
-                                                      `sort` array.
+sort_default              _team_    string  relevance The default sort criterion to use. Must be one of those in the
+                                                      `sort_options` array.

 
 

-sort_options              ranking   array   *Note 6*  List of supported sort criteria. Each element of the list is itself a
+sort_options              ranking   array   *Note 5*  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`.
 
                                                       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`.
 

-sp_auth_credentials       _global_  string
+sp_auth_credentials       _global_  string            If defined, this must be a slash-separated combination of username and
+                                                      password, which is sent as the authentication credentials on session
+                                                      initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
+                                                      section below.

 
 

-sp_auth_path              _global_  string
+sp_auth_path              _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2
+                                                      URLs](#assembling-pazpar2-urls) section below.

 
 

-sp_auth_query             _global_  string
+sp_auth_query             _global_  string  *Note 7*  Part of the URL used for authentication. See the [Assembling Pazpar2
+                                                      URLs](#assembling-pazpar2-urls) section below.

 
 

-target                    facet,    string
-                          facets,
-                          record,
+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.

                           records,
                           results
 
                           records,
                           results
 

-targetfilter              facet,    string
-                          facets,
-                          record,
+targetfilter              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.

                           records,
                           results
 
                           records,
                           results
 

-targets                   facet,    string
-                          facets,
-                          record,
+targets                   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.

                           records,
                           results
 
                           records,
                           results
 

-template                  details,  string
-                          done,
-                          facet,
-                          facets,
-                          images,
-                          lang,
+template                  details,  string            Numerous widgets use Handlebars templates to render HTML. In general, each
+                          done,                       of these by default uses a template with the same name as the widget
+                          facet,                      itself. Individual widgets can be customised to use a template of a
+                          facets,                     different name by means of their `template` setting. The `records` widget
+                          images,                     (and `record`, an equivalent that shows only a single record) use the
+                          lang,                       `summary` template as well as the `records` template.

                           navi,
                           pager,
                           progress,
                           ranking,
                           navi,
                           pager,
                           progress,
                           ranking,

-                          record,

                           records,
                           reference,
                           results,
                           records,
                           reference,
                           results,

@@ -1015,37 +1041,47 @@ template                  details,  string
                           switch,
                           targets
 
                           switch,
                           targets
 

-text                      builder   string
+<!--- 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
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather

-                                                      than raw Pazpar2.
+                                                      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
 

-1. ["sources", "subjects", "authors"]
+1. The default for `facets` is `["xtargets", "subject", "author"]`

 
 

-2. /pazpar2/search.pz2
+2. The default for `perpage_options` is `[10, 20, 30, 50]`

 
 

-3. [10, 20, 30, 50]
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`

 
 

-4. http://sp-mkws.indexdata.com/service-proxy-auth
+4. The default for `pp2_path` is `"service-proxy"`

 
 

-5. http://sp-mkws.indexdata.com/service-proxy/
+5. The default for `sort_options` is `[["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]`

 
 

-6. [["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"`.

 
 ### 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.
 
 FIXME !query!q, !path!2, etc.
 

+### 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`.
+

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