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 <url> element in the
POM?</question>
<answer>
<p>
- The Site Plugin uses the <url> 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 <url> 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
<url> element. If the project's site is not deployed anywhere,
then remove the <url> element from the POM.
</p>
<p>
+ On the other hand, the <distributionManagement.url> 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.
