Add support for search_aliases in the settings file.

Refs: https://todo.sr.ht/~valhalla/lesana/11

3 files changed, 25 insertions, 1 deletions

diff --git a/docs/source/man/lesana-search.rst b/docs/source/man/lesana-search.rst
index fff4b8e..f7bcf9c 100644
--- a/docs/source/man/lesana-search.rst
+++ b/docs/source/man/lesana-search.rst
@@ -7,7 +7,8 @@ SYNOPSIS
 
 lesana search [--help] [--collection COLLECTION] [--template TEMPLATE] \
   [--offset OFFSET] [--pagesize PAGESIZE] [--all] \
-  [--sort FIELD1 [--sort FIELD2 ...]] [query [query ...]]
+  [--expand-query-template] [--sort FIELD1 [--sort FIELD2 ...]] \
+  [query [query ...]]
 
 DESCRIPTION
 ===========
@@ -50,4 +51,6 @@ OPTIONS
 
    This option can be added multiple times; prefix the name of the field
    with ``-`` to reverse the results (e.g. ``--sort='-date'``).
+expand-query-template
+   Render search_aliases in the query as a jinja2 template
 
diff --git a/docs/source/user/search.rst b/docs/source/user/search.rst
index 41746a3..d14f37f 100644
--- a/docs/source/user/search.rst
+++ b/docs/source/user/search.rst
@@ -22,3 +22,21 @@ xapian for details.
 
 .. _`Query Parser`: https://getting-started-with-xapian.readthedocs.io/en/latest/concepts/search/queryparser.html
 
+.. _search aliases:
+
+Search templates and ``search_aliases``
+=======================================
+
+In some contexts, search queries are rendered as jinja2 templates with
+the contents of the ``search_aliases`` property as set in
+``settings.yaml``.
+
+The values of those search aliases should be valid search snippets with
+the syntax documented above; it's usually a good idea to wrap them in
+parenthesis, so that they are easier to use in complex queries; e.g.::
+
+   my_alias: '(name:object OR name:thing)'
+
+can correctly be used in a query like::
+
+   {{ my_alias }} AND description:shiny
diff --git a/docs/source/user/settings.rst b/docs/source/user/settings.rst
index 2d3a3fa..ba14e37 100644
--- a/docs/source/user/settings.rst
+++ b/docs/source/user/settings.rst
@@ -20,6 +20,9 @@ It is a yaml file with a dict of properties and their values.
    a list of field names (possibly prefixed by + or -) that are used by
    default to sort results of searches in the collection.
    The fields must be marked as sortable in their definition, see below.
+``search_aliases``:
+   a dict of <name>: <search snippet> which can be used in a query
+   template. For more details see :ref:`search aliases`
 ``fields``:
    The list of fields used by the collection, as described below.