Tweak table styling to make individual rows cohere better.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 13f51b4..14e8817 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -860,26 +860,37 @@ default values are in footnotes to keep the table reasonably narrow.
 ----
 Element                   Widget    Type    Default   Description
 --------                  ------    -----   --------- ------------
 ----
 Element                   Widget    Type    Default   Description
 --------                  ------    -----   --------- ------------

-auth_hostname             _global_
+auth_hostname             _global_  string            If provided, overrides the `pp2_hostname` setting when constructing the
+                                                      Service Proxy authentication URL. This need only be used when authentication
+                                                      is performed on a different host from the remaining operations (search,
+                                                      retrieve, etc.)

 
 

-autosearch                facet,
-                          facets,
+autosearch                facet,    string            If provided, this setting contains a query which is immediately run on behalf
+                          facets,                     of the team. Often used with an [indirect setting](#indirect-settings).

                           record,
                           records,
                           results
 
                           record,
                           records,
                           results
 

-facet                     facet
+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
+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
+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  en        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.

@@ -888,22 +899,22 @@ 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,
-                          facets,
-                          record,
+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
 
 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.
 
                           records,
                           results
 
 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,
+maxrecs                   facet,    int

                           facets,
                           record,
                           records,
                           results
 
                           facets,
                           record,
                           records,
                           results
 

-paragraphs                reference
+paragraphs                reference int

 
 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
 
 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

@@ -911,7 +922,7 @@ pazpar2_url               _global_  string  *Note 2*  The URL used to access the
                                                       an underlying Pazpar2 instance. In the latter case, `service_proxy_auth` must
                                                       be provided.
 
                                                       an underlying Pazpar2 instance. In the latter case, `service_proxy_auth` must
                                                       be provided.
 

-perpage                   facet,
+perpage                   facet,    int

                           facets,
                           record,
                           records,
                           facets,
                           record,
                           records,

@@ -922,9 +933,9 @@ perpage_default           _team_    string  20        The initial value for the
 perpage_options           ranking   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           ranking   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.
 

-pp2_hostname              _global_
+pp2_hostname              _global_  string

 
 

-pp2_path                  _global_
+pp2_path                  _global_  string

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

@@ -933,9 +944,9 @@ responsive_design_width   _global_  int               If defined, then the facet
                                                       threshhold width, in pixels, at which the facets move between their two
                                                       locations.
 
                                                       threshhold width, in pixels, at which the facets move between their two
                                                       locations.
 

-scan_all_nodes            _global_
+scan_all_nodes            _global_  bool

 
 

-sentences                 reference
+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
 
 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

@@ -955,7 +966,7 @@ show_sort                ranking    bool    true      Indicates whether or not t
 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, for switching between
                                                       showing retrieved records and target information.
 

-sort                      facet,
+sort                      facet,    string

                           facets,
                           record,
                           records,
                           facets,
                           record,
                           records,

@@ -969,31 +980,31 @@ sort_options              ranking   array   *Note 6*  List of supported sort cri
                                                       sort-expression such as `data:0` and the second is a human-readable label
                                                       such as `newest`.
 
                                                       sort-expression such as `data:0` and the second is a human-readable label
                                                       such as `newest`.
 

-sp_auth_credentials       _global_
+sp_auth_credentials       _global_  string

 
 

-sp_auth_path              _global_
+sp_auth_path              _global_  string

 
 

-sp_auth_query             _global_
+sp_auth_query             _global_  string

 
 

-target                    facet,
+target                    facet,    string

                           facets,
                           record,
                           records,
                           results
 
                           facets,
                           record,
                           records,
                           results
 

-targetfilter              facet,
+targetfilter              facet,    string

                           facets,
                           record,
                           records,
                           results
 
                           facets,
                           record,
                           records,
                           results
 

-targets                   facet,
+targets                   facet,    string

                           facets,
                           record,
                           records,
                           results
 
                           facets,
                           record,
                           records,
                           results
 

-template                  details,
+template                  details,  string

                           done,
                           facet,
                           facets,
                           done,
                           facet,
                           facets,

@@ -1012,7 +1023,7 @@ template                  details,
                           switch,
                           targets
 
                           switch,
                           targets
 

-text                      builder
+text                      builder   string

 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
                                                       than raw Pazpar2.
 
 use_service_proxy         _global_  bool    true      If true, then a Service Proxy is used to deliver searching services rather
                                                       than raw Pazpar2.

@@ -1039,6 +1050,9 @@ structure.)
 
 6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
 
 
 6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
 

+### Indirect settings
+
+FIXME !query!q, !path!2, etc.

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