[PATCH] Datacage ref doc: Explain dc:macro & Co

[Wald Commits]

# HG changeset patch
# User Sascha L. Teichmann <teichmann at intevation.de>
# Date 1381757269 -7200
# Node ID 00b17e77c2e82675c96cee1eea9975624c02d9c9
# Parent  52bc38e6bbe1a70c90ead866a28b2a850df3f826
Datacage ref doc: Explain dc:macro & Co.

diff -r 52bc38e6bbe1 -r 00b17e77c2e8 artifacts/doc/datacage_ref_de.rst
--- a/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 14:40:51 2013 +0200
+++ b/artifacts/doc/datacage_ref_de.rst	Mon Oct 14 15:27:49 2013 +0200
@@ -117,12 +117,73 @@
 
 Makros
 ~~~~~~
+Um innerhalb des Definitionsdokumentes Wiederholungen zu vermeiden, können sogenannte
+Makros definiert werden, die dann von anderer Stellen aus eingefügt werden können.
 
-``dc:macro`` **TODO**
+``dc:macro`` Wiederverwendbare Teile definieren
+...............................................
 
-``dc:macro-body`` **TODO**
+.. code:: xml
 
-``dc:call-macro`` **TODO**
+    <dc:macro name="Name">
+      ...
+    </dc:macro>
+
+Definiert ein Makro namens Name. Nach der Definition ist dieses dann unter diesem
+Namen global innerhalb des Definitionsdokumentes bekannt. Makros können geschachtelt
+werden. Auch eingeschachtelte Makros sind global sichtbar. Die Makrodefinition und
+ihre eingeschalteten Elemente werden nicht in das Ausgabedokument übernommen.
+
+``dc:call-macro`` Makros aufrufen
+
+.. code:: xml
+
+    <dc:call-macro name="Name">
+
+Ruft ein Makro names Name auf. Dieses muss mit `dc:macro` definiert sein. Die Reihenfolge
+von Definition und Aufruf ist egal.
+
+``dc:macro-body`` Elemente an ein Makro übergeben
+.................................................
+
+.. code:: xml
+
+    <dc:macro name="Name">
+      ...
+      <dc:macro-body/>
+      ...
+    </dc:macro>
+
+Um an Makros weitere Bausteine als Argument übergeben zu können, ist es optional
+möglich innerhalb einer Makrodefinition ein Element `dc:macro-body` einzufügen.
+Dieses Element expandiert sich zum Inhalt des `dc:call-macro`-Aufrufs.
+
+.. code:: xml
+
+    <dc:call-macro name="Name">Inhalt von dc:macro-body</dc:call-macro>
+
+Zur Verdeutlichung ein konkretes Beispiel
+
+.. code:: xml
+
+    <dc:macro name="Greetings">
+      <Hallo>
+          <dc:macro-body/>
+      </Hallo>
+    </dc:macro>
+
+    <dc:call-macro name="Greetings">Welt</dc:call-macro>
+    <dc:call-macro name="Greetings">Mond</dc:call-macro>
+
+Dies produziert folgende Ausgabe
+
+.. code:: xml
+
+    <Hallo>Welt</Hallo>
+    <Hallo>Mond</Hallo>
+
+Das Haupteinsatzgebiet dieses Konstruktes ist die transparente Bereitstellung
+von Kontexten, die dann verschiedentlich ausgewertet werden sollen.
 
 Sonstige Elemente
 ~~~~~~~~~~~~~~~~~