src/site/xdoc/download-page.xml - commons-build-plugin - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 -->
 <document>

     <properties>
         <title>Generating Download Page</title>
         <author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
     </properties>

     <body>


         <section name="commons-build:download-page" href="download-page">

             <subsection name="Overview">
                 <p>
                 The <code>commons-build:download-page</code> goal generates a custom Download page for the latest release of a component.
                 Execute the goal using the following command: <source>mvn commons-build:download-page</source>
                 </p>

                 <p>
                 The above command generates an <i>xdoc</i> page named download_<i>componentid</i><b>.xml</b> in either the <code>xdocs</code>
                 or <code>src/site/xdoc</code> directory (depending on which exists), which should be checked into subversion.
                 This will cause a download_<i>componentid</i><b>.html</b> page to be generated when the <code>mvn site</code> is run.
                 Remember to add a <i>Download</i> link to download_<i>componentid</i><b>.cgi</b> to the maven <code>site.xml</code>.
                 </p>

                 <p>
                 <strong>Note:</strong> The Download page should only need to be re-generated after a new release of the component
                 or if the download page template changes.
                 </p>

                 <p>
                 This goal uses the following:
                 <ul>
                     <li>The goal is mapped to the ant script/target using the <code>download-page</code> mojo defintion in the
                         <a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li>
                     <li>Executes the <code>download-page</code> target in
                         <a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a>
                         ant script</li>
                     <li>Uses either the
                         <a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/download-page-body.xml">download-page-body.xml</a> or
                         <a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/no-download-page-template.xml">no-download-page-template.xml</a>
                         template, depending on whether the <code>commons.release.version</code> property is set or not.
                         </li>
                     <li>Uses the <a href="download-page-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li>
                 </ul>
                 </p>
             </subsection>

             <subsection name="Configuration">
                 <p>
                 To generate a Download page, the following <a href="download-page-mojo.html">properties</a> are configured in the component's <code>pom.xml</code>
                 <ul>
                     <li><b>commons.componentid</b> - Commons component id</li>
                     <li><b>commons.release.version</b> - The version number of the latest release of the component</li>
                     <li><b>commons.release.name</b> - (<i>optional - defaults to <code>${commons.release.name}</code></i>) The name of the latest release of the component</li>
                     <li><b>commons.release.desc</b> - (<i>optional</i>) The download links are shown in a section with the component name and release version - if this parameter is specified then this text is appended</li>
                     <li><b>commons.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the binary release
                         (some components use "-bin", others have no suffix)</li>
                     <li><b>commons.release.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
                 </ul>
                 </p>
                 <p>
                 Example configuration for Commons Chain:
 <source><![CDATA[
     <properties>
         <commons.componentid>chain</commons.componentid>
         <commons.release.version>1.2</commons.release.version>
     </properties>
 ]]></source>
                 </p>

                 <p>
                 Sometimes there is a requirement to list two versions on the download page. This can be achieved using the following properties:
                 <ul>
                     <li><b>commons.release.2.version</b> - The version number of the alternative release of the component</li>
                     <li><b>commons.release.2.name</b> - (<i>optional - defaults to <code>${commons.release.2.name}</code></i>) The name of the alternative release of the component</li>
                     <li><b>commons.release.2.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
                     <li><b>commons.release.2.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
                         binary release (some components use "-bin", others have no suffix)</li>
                     <li><b>commons.release.2.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
                 </ul>
                 </p>
                 <p>
                 You can have a third version on the download page. This can be achieved using the following properties:
                 <ul>
                     <li><b>commons.release.3.version</b> - The version number of the alternative release of the component</li>
                     <li><b>commons.release.3.name</b> - (<i>optional - defaults to <code>${commons.release.3.name}</code></i>) The name of the alternative release of the component</li>
                     <li><b>commons.release.3.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
                     <li><b>commons.release.3.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
                         binary release (some components use "-bin", others have no suffix)</li>
                     <li><b>commons.release.3.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
                 </ul>
                 </p>
                 <p>
                 You can have a fourth version on the download page. This can be achieved using the following properties:
                 <ul>
                     <li><b>commons.release.4.version</b> - The version number of the alternative release of the component</li>
                     <li><b>commons.release.4.name</b> - (<i>optional - defaults to <code>${commons.release.4.name}</code></i>) The name of the alternative release of the component</li>
                     <li><b>commons.release.4.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
                     <li><b>commons.release.4.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
                         binary release (some components use "-bin", others have no suffix)</li>
                     <li><b>commons.release.4.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
                 </ul>
                 </p>
                 <p>
                 Example configuration for Commons DBCP with two releases:
 <source><![CDATA[
     <properties>
         <commons.componentid>dbcp</commons.componentid>
         <commons.release.version>1.4</commons.release.version>
         <commons.release.desc>for JDBC 4 (JDK 1.6)</commons.release.desc>
         <commons.release.2.version>1.3</commons.release.2.version>
         <commons.release.2.desc> for JDBC 3 (JDK 1.4-1.5)</commons.release.2.desc>
     </properties>
 ]]></source>
                 </p>
                 <p>
                 The above configuration generates a download page for two releases shown below:
                 </p>
                  <p>
                     <img src="download-page-2release.jpg" alt="Download Page with two release versions"/>
                 </p>
             </subsection>

         </section>

     </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<document>

	<properties>
	<title>Generating Download Page</title>
	<author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
	</properties>

	<body>


	<section name="commons-build:download-page" href="download-page">

	<subsection name="Overview">
	<p>
	The <code>commons-build:download-page</code> goal generates a custom Download page for the latest release of a component.
	Execute the goal using the following command: <source>mvn commons-build:download-page</source>
	</p>

	<p>
	The above command generates an <i>xdoc</i> page named download_<i>componentid</i><b>.xml</b> in either the <code>xdocs</code>
	or <code>src/site/xdoc</code> directory (depending on which exists), which should be checked into subversion.
	This will cause a download_<i>componentid</i><b>.html</b> page to be generated when the <code>mvn site</code> is run.
	Remember to add a <i>Download</i> link to download_<i>componentid</i><b>.cgi</b> to the maven <code>site.xml</code>.
	</p>

	<p>
	<strong>Note:</strong> The Download page should only need to be re-generated after a new release of the component
	or if the download page template changes.
	</p>

	<p>
	This goal uses the following:
	<ul>
	<li>The goal is mapped to the ant script/target using the <code>download-page</code> mojo defintion in the
	<a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.mojos.xml">generate-xdocs.mojos.xml</a> mapping document</li>
	<li>Executes the <code>download-page</code> target in
	<a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/scripts/generate-xdocs.build.xml">generate-xdocs.build.xml</a>
	ant script</li>
	<li>Uses either the
	<a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/download-page-body.xml">download-page-body.xml</a> or
	<a href="https://svn.apache.org/repos/asf/commons/proper/commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates/no-download-page-template.xml">no-download-page-template.xml</a>
	template, depending on whether the <code>commons.release.version</code> property is set or not.
	</li>
	<li>Uses the <a href="download-page-mojo.html">goal's (i.e. mojo's) parameters</a> to filter values in the template</li>
	</ul>
	</p>
	</subsection>

	<subsection name="Configuration">
	<p>
	To generate a Download page, the following <a href="download-page-mojo.html">properties</a> are configured in the component's <code>pom.xml</code>
	<ul>
	<li><b>commons.componentid</b> - Commons component id</li>
	<li><b>commons.release.version</b> - The version number of the latest release of the component</li>
	<li><b>commons.release.name</b> - (<i>optional - defaults to <code>${commons.release.name}</code></i>) The name of the latest release of the component</li>
	<li><b>commons.release.desc</b> - (<i>optional</i>) The download links are shown in a section with the component name and release version - if this parameter is specified then this text is appended</li>
	<li><b>commons.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the binary release
	(some components use "-bin", others have no suffix)</li>
	<li><b>commons.release.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
	</ul>
	</p>
	<p>
	Example configuration for Commons Chain:
	<source><![CDATA[
	<properties>
	<commons.componentid>chain</commons.componentid>
	<commons.release.version>1.2</commons.release.version>
	</properties>
	]]></source>
	</p>

	<p>
	Sometimes there is a requirement to list two versions on the download page. This can be achieved using the following properties:
	<ul>
	<li><b>commons.release.2.version</b> - The version number of the alternative release of the component</li>
	<li><b>commons.release.2.name</b> - (<i>optional - defaults to <code>${commons.release.2.name}</code></i>) The name of the alternative release of the component</li>
	<li><b>commons.release.2.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
	<li><b>commons.release.2.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
	binary release (some components use "-bin", others have no suffix)</li>
	<li><b>commons.release.2.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
	</ul>
	</p>
	<p>
	You can have a third version on the download page. This can be achieved using the following properties:
	<ul>
	<li><b>commons.release.3.version</b> - The version number of the alternative release of the component</li>
	<li><b>commons.release.3.name</b> - (<i>optional - defaults to <code>${commons.release.3.name}</code></i>) The name of the alternative release of the component</li>
	<li><b>commons.release.3.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
	<li><b>commons.release.3.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
	binary release (some components use "-bin", others have no suffix)</li>
	<li><b>commons.release.3.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
	</ul>
	</p>
	<p>
	You can have a fourth version on the download page. This can be achieved using the following properties:
	<ul>
	<li><b>commons.release.4.version</b> - The version number of the alternative release of the component</li>
	<li><b>commons.release.4.name</b> - (<i>optional - defaults to <code>${commons.release.4.name}</code></i>) The name of the alternative release of the component</li>
	<li><b>commons.release.4.desc</b> - (<i>optional</i>) Additional text to append to the section name of the alternative release</li>
	<li><b>commons.release.4.binary.suffix</b> - (<i>optional - defaults to <code>-bin</code></i>) The suffix for the alternative
	binary release (some components use "-bin", others have no suffix)</li>
	<li><b>commons.release.4.subdir</b> - The subdirectory to use. This defaults to using separate source/binaries folders; it set it will be used as the directory for both.</li>
	</ul>
	</p>
	<p>
	Example configuration for Commons DBCP with two releases:
	<source><![CDATA[
	<properties>
	<commons.componentid>dbcp</commons.componentid>
	<commons.release.version>1.4</commons.release.version>
	<commons.release.desc>for JDBC 4 (JDK 1.6)</commons.release.desc>
	<commons.release.2.version>1.3</commons.release.2.version>
	<commons.release.2.desc> for JDBC 3 (JDK 1.4-1.5)</commons.release.2.desc>
	</properties>
	]]></source>
	</p>
	<p>
	The above configuration generates a download page for two releases shown below:
	</p>
	<p>
	<img src="download-page-2release.jpg" alt="Download Page with two release versions"/>
	</p>
	</subsection>

	</section>

	</body>
	</document>