svn commit: r1422896 - in /maven/plugins/trunk/maven-site-plugin/src/site: apt/examples/multimodule.apt fml/faq.fml

[lt...@apache.org]

Author: ltheussl
Date: Mon Dec 17 12:22:03 2012
New Revision: 1422896

URL: http://svn.apache.org/viewvc?rev=1422896&view=rev
Log:
[MSITE-669] clarify usage of of distMngmnt url for staging and deploying

Modified:
    maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
    maven/plugins/trunk/maven-site-plugin/src/site/fml/faq.fml

Modified: maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt?rev=1422896&r1=1422895&r2=1422896&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt Mon Dec 17 12:22:03 2012
@@ -53,14 +53,30 @@ Building multi-module sites
   <<<site:deploy>>> but uses the <<<stagingDirectory>>> parameter as deployment location.
   This can be used to deploy the site to a remote staging area (<<<site:stage>>> is always local).
 
-  <<Note:>> If subprojects inherit the site URL from a parent POM, they will automatically
+  <<Notes:>>
+
+  * If subprojects inherit the (distribution) site URL from a parent POM, they will automatically
   append their <artifactId> to form their effective deployment location.
   This goes for both the project url and the url defined in the
-  <<<\<distributionManagement\>>>> element of the pom. If your multi-module tree does not
+  <<<\<distributionManagement\>>>> element of the pom.
+
+  * If your multi-module tree does not
   follow the maven conventions, or if module directories are named differently than
   module artifacts, you have to specify the url's for <<each>> child project.
   See also <<<{{{../faq.html#Use_of_url}How does the Site Plugin use the \<url\> element in the POM?}}>>>.
 
+  * The pom.xml of the topmost project in a multi-module build must define the distributionManagement URL
+  element (called "rootURL" hereafter). The rootURL must be the topmost distributionManagement URL
+  in the multi-module project, implying that any distributionManagement URL defined within another
+  project in a multimodule build must start with the rootURL and append unique paths
+  (to be situated "below" the rootURL).
+
+  * All projects in multi-module builds must define unique distributionManagement url elements,
+  below/under the root distributionManagement URL in terms of URL path.
+
+  * If the artifactId and module name (i.e. directory name) are not identical for any project within a
+  multi-module build, the distributionManagement URL element must be defined in the pom.xml file in the project.
+
 * Inheritance
 
   Site descriptors are inherited along the same lines as project descriptors

Modified: maven/plugins/trunk/maven-site-plugin/src/site/fml/faq.fml
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/fml/faq.fml?rev=1422896&r1=1422895&r2=1422896&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/fml/faq.fml (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/fml/faq.fml Mon Dec 17 12:22:03 2012
@@ -116,13 +116,17 @@ under the License.
       <question>How does the Site Plugin use the &lt;url&gt; element in the POM?</question>
       <answer>
         <p>
-          The Site Plugin uses the &lt;url&gt; element in the POM to create
-          relative links for the generated site. If your project has a URL
+          The Site Plugin does not use the &lt;url&gt; element in the POM.
+          The project URL is just a piece of information to let your users know
+          where the project lives. Some other plugins (e.g. the project-info-report-plugin)
+          may be used to present this information. If your project has a URL
           where the generated site is deployed, then put that URL into the
           &lt;url&gt; element. If the project's site is not deployed anywhere,
           then remove the &lt;url&gt; element from the POM.
         </p>
         <p>
+          On the other hand, the &lt;distributionManagement.url&gt; is used in a multi-module
+          build to construct relative links between the generated sub-module sites.
           In a multi module build it is important for the parent and child
           modules to have <strong>different</strong> URLs. If they have the
           same URL, then links within the combined site will not work.