From 38d8d0c3f814448b5259fc9bad5d61a4450ef8f1 Mon Sep 17 00:00:00 2001
From: Elena ``of Valhalla'' Grandi <valhalla@trueelena.org>
Date: Wed, 28 Oct 2020 15:57:39 +0100
Subject: Document the settings file

---
 docs/source/user/index.rst    |  1 +
 docs/source/user/settings.rst | 61 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/source/user/settings.rst

diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst
index 243b812..3b0a0f4 100644
--- a/docs/source/user/index.rst
+++ b/docs/source/user/index.rst
@@ -10,5 +10,6 @@ Documentation that is useful for everybody.
 
    getting_started_command_line
    moving_data_between_collections
+   settings
 
    derivatives
diff --git a/docs/source/user/settings.rst b/docs/source/user/settings.rst
new file mode 100644
index 0000000..68c4a0d
--- /dev/null
+++ b/docs/source/user/settings.rst
@@ -0,0 +1,61 @@
+*******************
+ The settings file
+*******************
+
+The file ``settings.yaml`` defines the properties of a collection.
+
+It is a yaml file with a dict of properties and their values.
+
+``name``:
+   the human readable name of the collection.
+``lang``:
+   the language of the collection; valid values are listed in the
+   `xapian stemmer`_ documentation and are usually either the English
+   name or the two letter ISO639 code of a language.
+``entry_label``:
+   a jinja2 template used to show an entry in the interface; beside the
+   entry fields two useful variables are ``eid`` for the full entry ID
+   and ``short_id`` for the short version.
+``fields``:
+   The list of fields used by the collection, as described below.
+
+.. _`xapian stemmer`: https://xapian.org/docs/apidoc/html/classXapian_1_1Stem.html
+
+Field definitions
+=================
+
+``name``:
+   a name for the field (computer readable: keeping it lowercase
+   alphabetic ascii is probably safer).
+``type``:
+   the type of the field: valid fields are listed in
+   :doc:`/reference/lesana.types` (see the ``name`` property for each
+   field)
+``index``:
+   whether this field should be indexed: valid values are ``free`` for
+   fields that should be available in the free text search and ``field``
+   for fields that should only be available by specifying the field name
+   in the search.
+``help``:
+   a description for the field; this is e.g. added to new entries as a
+   comment.
+``default``:
+   the default value to use when creating an entry.
+``prefix``:
+   the optional term prefix used inside xapian: if you don't know what
+   this means you should avoid using this, otherwise see `Term
+   Prefixes`_ on the xapian documentation for details.
+
+.. _`Term Prefixes`: https://xapian.org/docs/omega/termprefixes.html
+
+Some field types may add other custom properties.
+
+``list`` properties
+-------------------
+
+``list``:
+   the type of the entries in the list; note that neither lists of non
+   uniform values nor lists of lists are supported (if you need those
+   you can use the ``yaml`` generic type, or write your own derivative
+   with an additional type).
+
-- 
cgit v1.2.3