--- a/flys-artifacts/ChangeLog	Wed Jun 06 12:18:44 2012 +0000
+++ b/flys-artifacts/ChangeLog	Wed Jun 06 12:19:19 2012 +0000
@@ -1,3 +1,7 @@
+2012-06-06	Felix Wolfsteller	<felix.wolfsteller@intevation.de>
+
+	* doc/datacage.txt: More documentation of datacage conf.
+
 2012-06-06  Raimund Renkert <raimund.renkert@intevation.de>
 
 	Added new facet for analysis periods and updated facet names.

--- a/flys-artifacts/doc/datacage.txt	Wed Jun 06 12:18:44 2012 +0000
+++ b/flys-artifacts/doc/datacage.txt	Wed Jun 06 12:19:19 2012 +0000
@@ -82,3 +82,67 @@
 The "name" attribute is what is to be displayed in the client, the "ids" are given
 to the server and pass important information about the chosen data.
 The "factory" is chosen according to the type of data displayed.
+
+So far, three other elements have not yet been mentioned: <dc:comment>,
+<dc:if> and the <dc:when><dc:otherwise> structure.
+<dc:comment> is an element to allow comments.  Choose these over standard
+<!-- --> xml comments, because they are not transferred to the client.
+<dc:if> and <dc:when> allow control (rather: definition) flow within
+the configuration and work in analogy to the XSL-elements <xsl:if>
+and <xsl:when>.
+
+When dealing with the behaviour specification of the datacage, multiple
+interpretations for the term "context" are possible.
+A <dc:context> element essentially means a database binding.  Thus each
+query (<dc:statement>) needs to be nested in its own context.
+Furthermore, two types of databases with own bindings exist:
+The "system" (default for <dc:context>, <dc:context connection="system">)
+context allows queries related to the backend database with existing
+data (e.g. measurements).
+The "user" context (<dc:context connection="user">) allows queries against
+the database which stores information about already existing artifacts and
+calculations.
+
+Another connotation for the term "context" is the situation from which
+the datacage is queried.  The standard case is a from the datacage widget.
+When the user opens the datacage from the graphical client, this is done
+from one of possible multiple diagrams.
+When the datacage is queried, it gets as an argument the "out" of
+the current artifact.  The out corresponds to the diagram type.
+
+For example the inner block of
+
+          <dc:if test="dc:contains($artifact-outs, 'longitudinal_section')">
+              <longitudinal_section>
+                <dc:call-macro name="annotations"/>
+              </longitudinal_section>
+          </dc:if>
+
+will only be executed if called from the datacage within a
+longitudinal_section diagram.
+
+In the given example another concept of the datacage configuration is
+encountered: Macros.
+
+Macros help to avoid duplication of parts of the document.  As the datacage
+of some diagrams should include the same type of data, the same query should
+be executed in multiple situations.
+
+Therefore a macro can be defined, like in
+
+        <dc:macro name="basedata_4_heightmarks-wq">
+          <heightmarks>
+            <dc:context>
+              <dc:statement>
+                SELECT id          AS prot_id,
+                       description AS prot_description
+                FROM wsts WHERE kind = 4 AND river_id = ${river_id}
+              </dc:statement>
+              <dc:elements>
+              <!-- ... -->
+        </dc:macro>
+
+and invoked from another location within the document, e.g. with
+
+                <dc:call-macro name="basedata_4_heightmarks"/>
+.