From a50579b4038857e75593d74d61477cddb0419b7f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20tom=20W=C3=B6rden?= <h.tomwoerden@indiscale.com>
Date: Sat, 12 Nov 2022 21:31:09 +0100
Subject: [PATCH] DOC: enhance doc on converters

---
 src/doc/converters.rst | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/doc/converters.rst b/src/doc/converters.rst
index 74090cf8..610689fe 100644
--- a/src/doc/converters.rst
+++ b/src/doc/converters.rst
@@ -15,8 +15,6 @@ Converters may define additional functions that create further values. For
 example, a regular expresion could be used to get a date from a file name.
 
 
-
-
 A converter is defined via a yml file or part of it. The definition states
 what kind of StructureElement it treats (typically one).
 Also, it defines how children of the current StructureElement are
@@ -64,31 +62,45 @@ Standard Converters
 
 Directory Converter
 ===================
+The Directory Converter creates StructureElements for each File and Directory
+inside the current Directory. You can match a regular expression against the
+directory name using the 'match' key.
 
 Simple File Converter
 =====================
+The Simple File Converter does not create any children and is usually used if
+A file shall be used as it is and be inserted and referenced by other entities.
 
 Markdown File Converter
 =======================
+Reads a YAML header from Markdown files (if such a header exists) and creates
+children elements according to the structure of the header.
 
-Dict Converter
+DictElement Converter
 ==============
+Creates a child StructureElement for each key in the dictionary.
 
 Typical Subtree converters
 --------------------------
+The following StructureElement are typically created:
 
-- DictBooleanElementConverter
-- DictFloatElementConverter
-- DictTextElementConverter
-- DictIntegerElementConverter
-- DictListElementConverter
-- DictDictElementConverter
+- BooleanElement
+- FloatElement
+- TextElement
+- IntegerElement
+- ListElement
+- DictElement
+
+Scalar Value Converters
+=======================
+`BooleanElementConverter`, `FloatElementConverter`, `TextElementConverter`,  and
+`IntegerElementConverter` behave very similarly.
 
 These converters expect `match_name` and `match_value` in their definition
 which allow to match the key and the value, respectively.
 
 Note that there are defaults for accepting other types. For example,
-DictFloatElementConverter also accepts DictIntegerElements. The default
+FloatElementConverter also accepts IntegerElements. The default
 behavior can be adjusted with the fields `accept_text`, `accept_int`,
 `accept_float`, and `accept_bool`.
 
@@ -106,8 +118,6 @@ JSONFileConverter
 
 
 
-TextElementConverter
-====================
 
 TableConverter
 ==============
-- 
GitLab