You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jv...@apache.org on 2005/10/14 03:09:19 UTC
svn commit: r320958 - in /maven/components/trunk/maven-site: my-app/
src/site/ src/site/apt/ src/site/apt/guides/
src/site/apt/guides/introduction/ src/site/apt/guides/mini/
Author: jvanzyl
Date: Thu Oct 13 18:09:16 2005
New Revision: 320958
URL: http://svn.apache.org/viewcvs?rev=320958&view=rev
Log:
more updates to docs
Added:
maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt (with props)
Removed:
maven/components/trunk/maven-site/src/site/apt/site.apt
Modified:
maven/components/trunk/maven-site/my-app/pom.xml
maven/components/trunk/maven-site/src/site/apt/guides/header.apt
maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-archetypes.apt
maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-dependency-management.apt
maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-m1-m2.apt
maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-releasing.apt
maven/components/trunk/maven-site/src/site/apt/guides/toc.apt
maven/components/trunk/maven-site/src/site/site.xml
Modified: maven/components/trunk/maven-site/my-app/pom.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/my-app/pom.xml?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/my-app/pom.xml (original)
+++ maven/components/trunk/maven-site/my-app/pom.xml Thu Oct 13 18:09:16 2005
@@ -22,6 +22,7 @@
<filters>
<filter>src/main/filters/filters.properties</filter>
</filters>
+ <outputDirectory>${pom.build.directory}</outputDirectory>
<resources>
<resource>
<directory>src/main/resources</directory>
Modified: maven/components/trunk/maven-site/src/site/apt/guides/header.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/header.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/header.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/header.apt Thu Oct 13 18:09:16 2005
@@ -8,14 +8,17 @@
Documentation
-
-* Guides
+* Getting Started Guide
* {{{getting-started/index.html}Getting Started Guide}}
- * {{{plugin/guide-plugin-development.html}Plug-in Developer's Guide}}
+* Developer Guides
* {{{development/guide-m2-development.html}Guide to Developing Maven 2.x}}
* {{{development/guide-building-m2.html}Guide to Building Maven 2.x}}
+
+* Plug-in Guides
+
+ * {{{plugin/guide-plugin-development.html}Plug-in Developer's Guide}}
Modified: maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-archetypes.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-archetypes.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-archetypes.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-archetypes.apt Thu Oct 13 18:09:16 2005
@@ -15,6 +15,26 @@
provides a consistent means of generating Maven projects. Archetype will help authors create
Maven project templates for users, and provides users with the means to generate parameterized versions
of those project templates.
-
+ Using archetypes provides a great way to enable developers quickly in a way consistent with best practices employed
+ by your project or organization. Within the Maven project we use archetypes to try and get our users up and running
+ as quickly as possible by providing a sample project that demonstrates many of the features of Maven while introducing
+ new users to the best practices employed by Maven. In a matter of seconds a new user can have a working Maven project
+ to use a jumping board for investigating more of the features in Maven. We have also tried to make the Archetype
+ mechanism additive and by that we mean allowing portions of a project to captured in an archetype so that pieces
+ or aspects of a project can be added to existing projects. A good example of this is the Maven site archetype.
+ If, for example, you have used the quick start archetype to generate a working project you can then quickly
+ create a site for that project by using the site archetype within that existing project. You can do anything like
+ this with archetypes.
+
+ You may want to standardize J2EE development within your organization so you may want to provide archetypes
+ for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organizations
+ repository they are available for use by all developers within your organization.
+
+* What makes up an Archetype?
+
+ Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of
+ archetype and a set of {{{http://jakarta.apache.org/velocity}Velocity}} templates which make up the prototype
+ project. If you would like to know how to make your archetypes please refer to our
+ {{{../mini/guide-creating-archetypes.html}Guide to creating archetypes}}.
Modified: maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-dependency-management.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-dependency-management.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-dependency-management.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/introduction/introduction-to-dependency-management.apt Thu Oct 13 18:09:16 2005
@@ -1,36 +1,97 @@
------
- Introduction to Dependency Management
+ Introduction to dependency management
------
Jason van Zyl
------
12 October 2005
------
-Introduction to Dependency Management
+Introduction to dependency management
-* How to Maintain Versions of Dependencies
+ Dependency management is one of the features of Maven that is best know to users and is one of the areas where
+ Maven excels. There is not much difficulty in managing dependencies for a single a project, but when you start
+ getting into dealing with multi-module projects and applications that consist of tens or hundreds of modules this
+ is where Maven can help you a great deal in maintaining a high degree of control and stability.
+
+* How to maintain versions of dependencies in a multi-module
+
++----+
+
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <packaging>jar</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Application</name>
+ <url>http://app.mycompany.com</url>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <!-- Will the scope be inherited? -->
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
++----+
+
++----+
+
+<project>
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <!-- how to manage this version -->
+ <version>1.0-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>app-module-foo</artifactId>
+ <packaging>jar</packaging>
+ <!-- Is this inherited -->
+ <version>1.0-SNAPSHOT</version>
+ <name>Application Foo Module</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+
++----+
+
++----+
+
+<project>
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <!-- how to manage this version -->
+ <version>1.0-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+ <artifactId>app-module-foo</artifactId>
+ <packaging>jar</packaging>
+ <!-- Is this inherited -->
+ <version>1.0-SNAPSHOT</version>
+ <name>Application Foo Module</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ </dependency>
+ </dependencies>
+</project>
- In a multi-project
++----+
- so using something as geronimo/continuum/cargo as an example i can document that placing all deps used by the overall project in a TLP depMan section is the way to go?
-
- o use TLP for all deps used in a project
- o in each project declare the dep and using groupId/artifactId and scope
-
- if you provide exclusions in your dependency, and exclusions in your depMgmt, the exclusions are NOT merged...local always wins
-<jdcasey> it's only an issue for exclusions, because it's a complex element
-
- so exclusions in the depMan element at the parent level and child level are not merged? is that correct?
-<jason> and the child level will win for a given dependency?
-<jdcasey> um, not sure how that works...haven't looked at it, but I believe that's correct...
-<jdcasey> I'd have to look at the code
-
- and injection only happens if there isn't something in the way
-<jdcasey> :)
-
-injection in depMan
-
------
-
------
-
+~~ Exclusions in depMan and exclusions in child dep are not merged
+~~ What other gotchas?
Modified: maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-m1-m2.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-m1-m2.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-m1-m2.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-m1-m2.apt Thu Oct 13 18:09:16 2005
@@ -6,7 +6,8 @@
12 October 2005
------
- * repoclean
+~~ merge in the m1 FAQ
+~~ repoclean
** Projects using multiproject or project properties
@@ -21,4 +22,4 @@
http://blogs.codehaus.org/people/vmassol/archives/001170_javazone_2005.html
-~~ doco coming from jay hartley
\ No newline at end of file
+~~ doco coming from jay hartley
Modified: maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-releasing.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-releasing.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-releasing.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-releasing.apt Thu Oct 13 18:09:16 2005
@@ -6,6 +6,8 @@
12 October 2005
-----
+~~ integrate releasing document
+
Releasing
The release plugin provides some basic functionality for making releases, and updating
Added: maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt?rev=320958&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt Thu Oct 13 18:09:16 2005
@@ -0,0 +1,224 @@
+ ------
+ Guide to creating a site
+ ------
+ Brett Porter
+ Jason van Zyl
+ ------
+ 13 May 2005
+ ------
+
+Creating a site
+
+* Creating Content
+
+ The first step to creating your site is to create some content. In Maven 2.0, the site content is separated by format,
+ as there are several available.
+
+-------------------
++- src/
+ +- site/
+ +- apt/
+ | +- index.apt
+ |
+ +- xdoc/
+ | +- other.xml
+ |
+ +- fml/
+ | +- general.fml
+ | +- faq.fml
+ |
+ +- site.xml
+--------------------
+
+ The Xdoc format is the same as {{{http://maven.apache.org/using/site.html} used in Maven 1.0}}. However, <<<navigation.xml>>>
+ has been replaced by the site descriptor (see below).
+
+ The APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this)
+ very quickly. A full reference of the {{{apt-format.html} APT Format}} is available.
+
+ The FML format is the FAQ format, also used in Maven 1.0.
+
+ Other formats are available, but at this point these 3 are the best tested. There are also several possible output formats,
+ but as of 2.0, only XHTML is available.
+
+ Note that all of the above is optional - just one index file is required in one of the input trees. Each of the paths will be merged
+ together to form the root directory of the site.
+
+* Generating The Site
+
+ Generating the site is very simple, and fast!
+
+---------------
+m2 site:site
+---------------
+
+ The resulting site will be in <<<target/site/...>>>
+
+ For more information on the site plugin, see the {{{plugins/maven-site-plugin/} plugin reference}}.
+
+* Deploying The Site
+
+ To be able to deploy the site, you must first declare a location to distribute to in your <<<pom.xml>>>, similar to the repository for
+ deployment.
+
+---------------
+<distributionManagement>
+ <site>
+ <id>website</id>
+ <url>scp://www.mycompany.com/www/docs/project/</url>
+ </site>
+</distributionManagement>
+---------------
+
+ The <<<id>>> element identifies the repository, so that you can attach credentials to it in your <<<settings.xml>>>
+ file in the same way as you would for any other repository. The URL gives the location to deploy to. Currently,
+ only SSH is supported, as above which copies to the host <<<www.mycompany.com>>> in the path <<</www/docs/project/>>>.
+
+ Deploying the site is done with the <<<site:deploy>>> goal. Note that you cannot just call the deployment goal on its own, however.
+ You must presently run the <<<site:site>>> goal as well.
+
+---------------
+m2 site:site site:deploy
+---------------
+
+ <<Note:>> the trailing slash in the URL above indicates that any subprojects that inherit this value should append their artifact ID to
+ the path instead of using it as-is.
+
+* Creating a Site Descriptor
+
+ The <<<site.xml>>> file is used to describe the layout of the site, and replaces the navigation file used in Maven 1.0.
+
+ A sample is given below:
+
+--------------------
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project name="Maven">
+ <bannerLeft>
+ <name>Maven</name>
+ <src>http://maven.apache.org/images/apache-maven-project.png</src>
+ <href>http://maven.apache.org/</href>
+ </bannerLeft>
+ <bannerRight>
+ <src>http://maven.apache.org/images/maven-small.gif</src>
+ </bannerRight>
+ <body>
+ <links>
+ <item name="Apache" href="http://www.apache.org/" />
+ <item name="Maven 1.0" href="http://maven.apache.org/"/>
+ <item name="Maven 2" href="http://maven.apache.org/maven2/"/>
+ </links>
+
+ <menu name="Maven 2.0">
+ <item name="Introduction" href="index.html"/>
+ <item name="Download" href="download.html"/>
+ <item name="Release Notes" href="release-notes.html" />
+ <item name="General Information" href="about.html"/>
+ <item name="For Maven 1.0 Users" href="maven1.html"/>
+ <item name="Road Map" href="roadmap.html" />
+ </menu>
+
+ ${reports}
+
+ ...
+ </body>
+</project>
+--------------------
+
+ ~~TODO: deserves more explanation.
+
+ Note the <<<${reports}>>> string in the navigation. When building the site, this is replaced by menus for any reports
+ that you have configured.
+
+* Adding Extra Resources
+
+ You can add any arbitrary resources to you site by including them in a
+ <<<resources>>> directory as shown below. Additional CSS files will be picked up
+ when they are placed in the <<<css>>> directory within the <<<resources>>>
+ directory.
+
+-------------------
++- src/
+ +- site/
+ +- resources/
+ +- css/
+ | +- site.css
+ |
+ +- images/
+ +- pic1.jpg
+--------------------
+
+ The file <<<site.css>>> will be added to the default XHTML output, so can be used to adjust the default Maven stylesheets if desired.
+
+ The file <<<pic1.jpg>>> will be available via a relative reference to the <<<images>>> directory from any page in your site.
+
+* Configuring Reports
+
+ Maven has several reports that you can add to your web site to display the current state of the project.
+ These reports take the form of plugins, just like those used to build the project.
+
+ To add these reports to your site, you must add the plugins to a special <<<reporting>>> section in the POM. The
+ following example shows how to configure the standard project information reports that display information from the
+ POM in a friendly format:
+
+-------------------
+<project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+-------------------
+
+ If you have included the appropriate <<<${reports}>>> tag in your <<<site.xml>>> descriptor, then when you regenerate
+ the site those items will appear on the menu.
+
+ ~~TODO: explain report sets
+
+* Internationalisation
+
+ Internationalisation in Maven is very simple, as long as the reports you are using have that particular locale
+ defined.
+
+ To enable multiple locales, add configuration similar to the following to your POM:
+
+-------------------
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <configuration>
+ <locales>en,fr</locales>
+ </configuration>
+ </plugin>
+ </plugins>
+ ...
+-------------------
+
+ This will generate both an English and a French version of the site. If <<<en>>> is your current locale, then it will
+ be generated at the root of the site, with a copy of the French translation of the site in the <<<fr/>>> subdirectory.
+
+ To add your own content for that translation instead of using the default, place a subdirectory with that locale
+ name in your site directory and create a new site descriptor with the locale in the file name. For example:
+
+-------------------
++- src/
+ +- site/
+ +- apt/
+ | +- index.apt (Default version)
+ +- fr/
+ | +- apt/
+ | | +- index.apt (French version)
+ +- site.xml (Default site descriptor)
+ +- site_fr.xml (French site descriptor)
+--------------------
+
+ With one site descriptor per language, the translated site(s) can evolve independently.
+
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/mini/guide-site.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Modified: maven/components/trunk/maven-site/src/site/apt/guides/toc.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/toc.apt?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/toc.apt (original)
+++ maven/components/trunk/maven-site/src/site/apt/guides/toc.apt Thu Oct 13 18:09:16 2005
@@ -8,17 +8,20 @@
Documentation
-
-* Guides
+* Getting Started Guide
* {{{getting-started/index.html}Getting Started Guide}}
- * {{{plugin/guide-plugin-development.html}Plug-in Developer's Guide}}
+* Developer Guides
* {{{development/guide-m2-development.html}Guide to Developing Maven 2.x}}
* {{{development/guide-building-m2.html}Guide to Building Maven 2.x}}
+* Plug-in Guides
+
+ * {{{plugin/guide-plugin-development.html}Plug-in Developer's Guide}}
+
* Mini Guides
* {{{mini/guide-apt-format.html}Guide to the APT Format}}
@@ -63,6 +66,10 @@
* {{{mini/guide-proxies.html}Guide to using proxies}}
+ * {{{mini/guide-releasing.html}Guide to Releasing}}
+
+ * {{{mini/guide-site.html}Guide to creating a site}}
+
* {{{mini/guide-test-customization.html}Guide to test customization}}
* {{{mini/guide-using-extensions.html}Guide to using Extensions}}
@@ -74,7 +81,7 @@
* {{{introduction/introduction-to-archetypes.html}Introduction to Archetypes}}
- * {{{introduction/introduction-to-dependency-management.html}Introduction to Dependency Management}}
+ * {{{introduction/introduction-to-dependency-management.html}Introduction to dependency management}}
* {{{introduction/introduction-to-repositories.html}Introduction to Repositories}}
Modified: maven/components/trunk/maven-site/src/site/site.xml
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/site.xml?rev=320958&r1=320957&r2=320958&view=diff
==============================================================================
--- maven/components/trunk/maven-site/src/site/site.xml (original)
+++ maven/components/trunk/maven-site/src/site/site.xml Thu Oct 13 18:09:16 2005
@@ -42,6 +42,7 @@
</menu>
-->
+ <!--
<menu name="Plugin Developers">
<item name="Plugin Development Guide" href="/developers/plugin-development-guide.html"/>
</menu>
@@ -50,6 +51,8 @@
<item name="Documentation Needed" href="/docs-required.html"/>
<item name="Building Maven 2.0" href="/developers/building.html"/>
</menu>
+ -->
+
<menu name="Reference">
<item name="Project Descriptor" href="/maven-model/maven.html"/>
<item name="Settings Descriptor" href="/maven-settings/settings.html"/>