Tweak.

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

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 81daf67..c868b5a 100644 (file)
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -932,15 +932,15 @@ perpage                   facet,    int               Specifies the number of re
 
 perpage_default           _team_    string  20        The initial value for the number of records to show on each page.
 
 
 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  *Note 7*  Unless overridden by the `pazpar2_url` setting, this is used together with
+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` 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  *Note 8*  Unless overridden by the `pazpar2_url` setting, this is used together with
+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.
                                                       `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.

@@ -989,7 +989,7 @@ sort                      facet,    string            Specifies the order in whi
 sort_default              _team_    string  relevance The default sort criterion to use. Must be one of those in the
                                                       `sort_options` 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`.

@@ -999,10 +999,10 @@ sp_auth_credentials       _global_  string            If defined, this must be a
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 
                                                       initialisation. See the [Assembling Pazpar2 URLs](#assembling-pazpar2-urls)
                                                       section below.
 

-sp_auth_path              _global_  string  *Note 9*  Part of the URL used for authentication. See the [Assembling Pazpar2
+sp_auth_path              _global_  string  *Note 6*  Part of the URL used for authentication. See the [Assembling Pazpar2

                                                       URLs](#assembling-pazpar2-urls) section below.
 
                                                       URLs](#assembling-pazpar2-urls) section below.
 

-sp_auth_query             _global_  string  *Note 10* Part of the URL used for authentication. See the [Assembling Pazpar2
+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            One of three ways to select which targets an auto-searching widgets uses. See
                                                       URLs](#assembling-pazpar2-urls) section below.
 
 target                    facet,    string            One of three ways to select which targets an auto-searching widgets uses. See

@@ -1023,17 +1023,16 @@ targets                   facet,    string            One of three ways to selec
                           records,
                           results
 
                           records,
                           results
 

-template                  details,  string            Numerous widgets use Handlebars templates ### say more!
-                          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,

@@ -1050,37 +1049,32 @@ 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
 

-1. ["xtargets", "subject", "author"]
-
-2. ### unused
-
-3. [10, 20, 30, 50]
+1. The default for `facets` is `["xtargets", "subject", "author"]`

 
 

-4. ### unused
+2. The default for `perpage_options` is `[10, 20, 30, 50]`

 
 

-5. "http://sp-mkws.indexdata.com/service-proxy/"
+3. The default for `pp2_hostname` is `"sp-mkws.indexdata.com"`

 
 

-6. [["relevance"], ["title:1", "title"], ["date:0", "newest"], ["date:1", "oldest"]]
+4. The default for `pp2_path` is `"service-proxy"`

 
 

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

 
 

-8. "service-proxy"
+6. The default for `sp_auth_path` is `"service-proxy/"`.

 
 

-9. The default for `sp_auth_path` is `"service-proxy/"`.
-
-10. The default for `sp_auth_query` is `"command=auth&action=perconfig"`.
+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.
 
 ### Assembling Pazpar2 URLs
 FIXME !query!q, !path!2, etc.
 
 ### Assembling Pazpar2 URLs