Add basic configuration documentation.

diff --git a/doc/markdown/configuration/composites.md b/doc/markdown/configuration/composites.md
new file mode 100644 (file)
index 0000000..2fa3ea5
--- /dev/null
+++ b/doc/markdown/configuration/composites.md
@@ -0,0 +1,61 @@
+# Rspamd composite rules
+
+Rspamd composites are used to combine rules and create more complex rules.
+Composite rules are defined by `composite` keys. The value of this key should be
+an object that defines composite's name and value, which is the combination of rules
+in a joint expression.
+
+For example, you can define a composite that is added when two of symbols are found:
+
+~~~nginx
+composite {
+       name = "TEST_COMPOSITE";
+       expression = "SYMBOL1 and SYMBOL2";
+}
+~~~
+
+In this case, if a message has `SYMBOL1` and `SYMBOL2` simultaneously then they are replaced by
+symbol `TEST_COMPOSITE`. The weights of `SYMBOL1` and `SYMBOL2` are substracted from the metric
+accordingly.
+
+## Composite expression
+
+You can use the following operations in a composite expression:
+
+* `AND` `&` - matches true only if both of operands are true
+* `OR` `|` - matches true if any of operands are true
+* `NOT` `!` - matches true if operand is false
+
+You also can use braces to define priorities. Otherwise operators are evaluated from left to right.
+For example:
+
+~~~nginx
+composite {
+    name = "TEST";
+    expression = "SYMBOL1 and SYMBOL2 and ( not SYMBOL3 | not SYMBOL4 | not SYMBOL5 )";
+}
+~~~
+
+Composite rule can include other composites in the body. There is no restriction of definition order:
+~~~nginx
+composite {
+    name = "TEST1";
+    expression = "SYMBOL1 AND TEST2";
+}
+composite {
+    name = "TEST2";
+    expression = "SYMBOL2 OR NOT SYMBOL3";
+}
+~~~
+
+Composites should not be recursive and it is normally detected by rspamd.
+
+## Composite weights rules
+Composites can leave the symbols in a metric or leave their weights. That could be used to create
+non-captive composites.
+For example, you have symbol `A` and `B` with weights `W_a` and `W_b` and a composite `C` with weight `W_c`.
+
+* If `C` is `A & B` then if rule `A` and rule `B` matched then these symbols are *removed* and their weights are removed as well, leading to a single symbol `C` with weight `W_c`.
+* If `C` is `-A & B`, then rule `A` is preserved, but the symbol `C` is inserted. The weight of `A` is preserved as well, so the total weight of `-A & B` will be `W_a + W_c`.
+* If `C` is `~A & B`, then rule `A` is *removed* but its weight is *preserved*, leading to a single symbol `C` with weight `W_a + W_c`
+

diff --git a/doc/markdown/configuration/index.md b/doc/markdown/configuration/index.md
index ae9ce749693ddd6297bc06ab0c9d1fa616ed9428..9ddf49689509a125f646b292d43be569647bf21c 100644 (file)
--- a/doc/markdown/configuration/index.md
+++ b/doc/markdown/configuration/index.md
@@ -4,6 +4,17 @@ Rspamd uses UCL for its configuration. UCL format is described in details in
 this [document](ucl.md). Rspamd defines several variables and macros to extend
 UCL functionality.
 
+## Table of Contents
+
+* [Options](options.md)
+* [Logging](logging.md)
+* [Metrics](metrics.md)
+* [Composites](composites.md)
+* [User settings](settings.md)
+* [Statistic configuration](statistic.md)
+* [Workers](../workers/index.md)
+* [Modules](../modules/index.md)
+
 ## Rspamd variables
 
 - *CONFDIR*: configuration directory for rspamd, it is $PREFIX/etc/rspamd/
@@ -50,7 +61,7 @@ metric settings, including rules weights and rspamd actions. [Workers](workers.m
 section specifies rspamd workers settings. [Composites](composites.md) is an utility
 section that describes composite symbols. Statistical filters are defined in 
 [statistic](statistic.md) section. Rspamd stores modules configuration (for both lua
-and internal modules) in [modules](modules.md) section while modules itself are
+and internal modules) in [modules](../modules/index.md) section while modules itself are
 loaded from the following portion of configuration:
 
 ~~~nginx
@@ -65,7 +76,7 @@ If directory is used then all files with suffix `.lua` are loaded as lua plugins
 
 This configuration is not intended to be changed by user, but you can include your
 own configuration in further. To redefine symbols weight and actions rspamd encourages
-to use [dynamic configuration](dynamic_conf.md). Nevertheless, rspamd installation
+to use [dynamic configuration](settings.md). Nevertheless, rspamd installation
 script will never rewrite user's configuration if it exists already. So please 
 read ChangeLog carefully if you upgrade rspamd to a new version for all incompatible
-configuration changes.
\ No newline at end of file
+configuration changes.

diff --git a/doc/markdown/configuration/logging.md b/doc/markdown/configuration/logging.md
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/doc/markdown/configuration/metrics.md b/doc/markdown/configuration/metrics.md
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/doc/markdown/configuration/options.md b/doc/markdown/configuration/options.md
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/doc/markdown/configuration/statistic.md b/doc/markdown/configuration/statistic.md
new file mode 100644 (file)
index 0000000..e69de29