DOC: enhance doc on converters

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
 ==============