ENH: more documentation for complex macro usage

src/doc/macros.rst

@@ -231,3 +231,43 @@ positions. Consider:
 
 However, this should not be a real limitation, as the crawler is designed in a way,
 that the order of the nodes in the same level should not matter.
+
+
+Using macros within macro definitions
+=====================================
+
+It is possible to use other macros in macro definitions. Again, examples can be found in
+the macro unit tests (see e.g. :func:`unittests.test_macros.test_macros_in_macros`):
+
+.. _example_macros_in_macros:
+.. code-block:: yaml
+
+  ---
+  metadata:
+    crawler-version: 0.3.1
+    macros:
+      - !defmacro
+        name: one_macro
+        params:
+          a: 25
+        definition:
+          macro_sub_$a:
+            b: $a
+            another_param: 3
+      - !defmacro
+        name: test_macrodef
+        params: {}
+        definition:
+          macro_top: !macro
+            one_macro:
+            - a: 17
+            - {}
+            - a: 98
+            not_macro:
+              a: 26
+  ---
+  extroot: !macro
+      test_macrodef:
+
+TODO:
+to be continued