[DOXIASITETOOLS-158] added documentation about interpolation (late and early)
git-svn-id: https://svn.apache.org/repos/asf/maven/doxia/doxia-sitetools/trunk@1736723 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/doxia-integration-tools/src/site/apt/index.apt b/doxia-integration-tools/src/site/apt/index.apt
index 2b7a6a4..e681081 100644
--- a/doxia-integration-tools/src/site/apt/index.apt
+++ b/doxia-integration-tools/src/site/apt/index.apt
@@ -38,3 +38,36 @@
* Usage
Instructions on how to use the integration of Doxia in Maven can be found {{{./usage.html}here}}.
+
+* <<<site.xml>>> Decoration Model Interpolation
+
+ Interpolation of {{{../doxia-decoration-model/decoration.html}<<<site.xml>>> decoration model}} injects
+ Maven project's information, replacing <<<$\{...\}>>> with calculated values
+ like it happens in {{{/ref/current/maven-model-builder/#Model_Interpolation}Maven model interpolation}}.
+
+ Interpolation can be <<late>> or <<early>>:
+
+ * with <<late>> interpolation, replacement happens <<after>> inheritance. This is the classical behaviour in Maven pom,
+
+ * with <<early>> interpolation, replacement happens <<before>> inheritance: this was the default behaviour for <<<project.*>>>
+ values until Doxia Sitetools 1.7, when these early and late interpolation definitions didn't exist.
+ Since Doxia Sitetools 1.7.1, early interpolation happens for <<<this.*>>> values.
+
+ []
+
+ Values are evaluated in sequence from different syntaxes:
+
+*-------------+--------------+--------------------+------------------+
+|| late value || early value || evaluation result || common examples ||
+*-------------+--------------+--------------------+------------------+
+| <<<project.*>>>\
+<<<*>>> (<deprecated>) | <<<this.*>>> | POM content (see {{{/ref/current/maven-model/maven.html}POM reference}}) | <<<$\{project.version\}>>>\
+ | | | <<<$\{this.url\}>>>
+*-------------+--------------+--------------------+------------------+
+| <<<*>>> | <<<this.*>>> | model properties, such as project properties set in the pom | <<<$\{any.key\}>>>\
+ | | | <<<$\{this.any.key\}>>>
+*-------------+--------------+--------------------+------------------+
+| <<<env.*>>>\
+<<<*>>> | <<<env.*>>>\
+ | <<<*>>> | environment variables | <<<$\{env.PATH\}>>>\
+*-------------+--------------+--------------------+------------------+
diff --git a/doxia-integration-tools/src/site/site.xml b/doxia-integration-tools/src/site/site.xml
index d048eac..e2e57b3 100644
--- a/doxia-integration-tools/src/site/site.xml
+++ b/doxia-integration-tools/src/site/site.xml
@@ -32,6 +32,10 @@
<!--item name="FAQ" href="faq.html"/-->
</menu>
+ <menu name="Reference">
+ <item name="site.xml Decoration Model" href="../doxia-decoration-model/decoration.html"/>
+ </menu>
+
<menu ref="reports" />
</body>
</project>
diff --git a/doxia-site-renderer/src/site/site.xml b/doxia-site-renderer/src/site/site.xml
index d6eeb6c..ebe51fe 100644
--- a/doxia-site-renderer/src/site/site.xml
+++ b/doxia-site-renderer/src/site/site.xml
@@ -34,6 +34,11 @@
<!--item name="FAQ" href="faq.html"/-->
</menu>
+ <menu name="Reference">
+ <item name="site.xml Decoration Model" href="../doxia-decoration-model/decoration.html"/>
+ <item name="Skin Model" href="../doxia-skin-model/skin.html"/>
+ </menu>
+
<menu ref="reports"/>
</body>
