You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by hb...@apache.org on 2010/03/21 15:10:52 UTC
svn commit: r925768 - in
/maven/archetype/trunk/archetype-plugin/src/site/apt/specification:
archetype-catalog.apt archetype-metadata.apt archetype.apt
create-from-project.apt generate.apt specification.apt
Author: hboutemy
Date: Sun Mar 21 14:10:52 2010
New Revision: 925768
URL: http://svn.apache.org/viewvc?rev=925768&view=rev
Log:
documentation enhancements
Modified:
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/generate.apt
maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-catalog.apt Sun Mar 21 14:10:52 2010
@@ -33,10 +33,10 @@ How the Archetype Plugin knows about arc
The catalogs are xml files.
- The Archetype Plugin comes bundled with an internal catalog.
+ The Archetype Plugin comes bundled with an internal catalog.
This one is used by default.
- The Archetype Plugin can use catalogs from local filesystem and from HTTP
+ The Archetype Plugin can use catalogs from local filesystem and from HTTP
connections.
* Catalog file explained
@@ -65,54 +65,53 @@ How the Archetype Plugin knows about arc
[[3]] The version of the archetype. <<<RELEASE>>> is a valid version. <<REQUIRED>>
- [[4]] The repository where to find the archetype. <<OPTIONAL>>. When
- ommitted, the archetype is searched for in the repository where the catalog
+ [[4]] The repository where to find the archetype. <<OPTIONAL>>. When
+ ommitted, the archetype is searched for in the repository where the catalog
comes from.
[[5]] The description of the archetype. <<OPTIONAL>>
-
+
* Archetype selection explained
During the creation of a project from an archetype, the Archetype Plugin
- ask the user to choose an archetype from a list containing the archetypes
- from each of the provided catalogs (Yes, there may be many).
+ asks the user to choose an archetype from a list containing the archetypes
+ from each of the provided catalogs (yes, there may be many).
- For each archetype in the list the Archetype Plugin shows a line like:
+ For each archetype in the list, the Archetype Plugin shows a line like:
+---
1: internal -> appfuse-basic-jsf (AppFuse archetype for creating a web application with Hibernate, Spring and JSF)
+---
- * <<<1:>>> The index of the archetype in the aggregated list (starting from
+ * <<<1:>>> The index of the archetype in the aggregated list (starting from
1).
* <<<internal>>> The name of the catalog where the archetype is originating.
* <<<appfuse-basic-jsf>>> The artifactId of the archetype
- * <<<(AppFuse archetype...)>>> The description of the archetype as found in
+ * <<<(AppFuse archetype...)>>> The description of the archetype as found in
the catalog.
* Creating a catalog file
At the end of the <<<create-from-project>>> behaviour, the Archetype Plugin
- install/deploy the archetype, and update the local/remote catalog.
-
- The <<<crawl-repository>>> goal is used to create a catalog file by crawling
- a Maven 2 repository located in the filesystem.
-
+ installs/deploys the archetype, and updates the local/remote catalog.
+
+ The <<<crawl-repository>>> goal is used to create a catalog file by crawling
+ a Maven 2 repository located in the filesystem.
+
* Location of catalog files
- The Archetype Plugin knows by default its internal catalog. It also knows
- about the <<<local>>> and <<<remote>>> catalogs.
+ The Archetype Plugin knows by default its internal catalog. It also knows
+ about the <<<local>>> and <<<remote>>> catalogs.
<<<local>>> represents the catalog file <<<~/.m2/archetype-catalog.xml>>>.
<<<remote>>> represents the catalog file <<<http://repo1.maven.org/maven2/archetype-catalog.xml>>>.
- The Archetype Plugin can also read catalogs from filesystem/HTTP by
+ The Archetype Plugin can also read catalogs from filesystem/HTTP by
providing the path/URL of a catalog file or of a directory containing the
<<<archetype-catalog.xml>>> file.
-
\ No newline at end of file
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype-metadata.apt Sun Mar 21 14:10:52 2010
@@ -32,12 +32,12 @@ How metadata on an archetype is stored?
The metadata about an archetype is stored in the <<<archetype-metadata.xml>>> file
located in the directory <<<META-INF/maven>>> of its jar file.
- The metadata file stores the additional properties, with corresponding
+ The metadata file stores the additional properties, with corresponding
default values.
It also stores the project's generated files in filesets.
- Finally it also stores inner modules of the archetype, which enable the
+ Finally it also stores inner modules of the archetype, which enable the
creation of multi-module projects using a single archetype.
A minimal <<<archetype-metadata.xml>>> file looks like:
@@ -57,21 +57,21 @@ How metadata on an archetype is stored?
+---
This example above shows:
-
+
* the archetype name is <<<basic>>>
- * the archetype defines a single fileset:
-
+ * the archetype defines a single fileset:
+
* the fileset will take all the files in <<<archetype-resources/src/main/java>>>
that match the <<<**/*.java>>> pattern
- * the selected files will be generated using the Velocity engine
+ * the selected files will be generated using the Velocity engine
(<<<filtered=true>>>)
- * the files will be generated in the <<<src/main/java>>> directory of the
- generated project in the same directory as in the jar file, but with
+ * the files will be generated in the <<<src/main/java>>> directory of the
+ generated project in the same directory as in the jar file, but with
that directory prepended by the package property.
-
+
[]
[]
@@ -81,7 +81,7 @@ How metadata on an archetype is stored?
The main properties that are used by the Velocity engine during a project's file generation are groupId, artifactId, version and package.
- It is possible to define additional properties that must be valued before the file generation.
+ It is possible to define additional properties that must be valued before the file generation.
These additional properties can be provided with default values, which enable not to ask the user for there values.
@@ -98,36 +98,36 @@ How metadata on an archetype is stored?
...
</archetype-descriptor>
+---
-
+
Here two additional properties are defined: <<<property-without-default>>>
and <<<property-with-default>>>.
- Be aware that the property keys can not contain any dots as they are
+ Be aware that the property keys can not contain any dots as they are
Velocity properties.
* Defining specific filesets
The filesets contained in the <<<archetype-metadata.xml>>> file defines the way
- the project's files located in the jar file are used by the Archetype Plugin
+ the project's files located in the jar file are used by the Archetype Plugin
to generate a project.
- Filesets must define the directory where the files will be searched for
- which is also the directory where the project's files will be generated.
- The first is the directory inside the archetype jar file, the second is the
+ Filesets must define the directory where the files will be searched for
+ which is also the directory where the project's files will be generated.
+ The first is the directory inside the archetype jar file, the second is the
directory in the generated project's tree.
- Filesets also defines the inclusion/exclusion of files "Ã la " ant.
- This provide a powerful way to describe a large set of files to be selected
+ Filesets also defines the inclusion/exclusion of files "<Ã la>" ant.
+ This provide a powerful way to describe a large set of files to be selected
for the generation process.
- Filesets can be filtered, which means the selected files will be used
- as Velocity templates. They can be non-filtered, which means the selected
+ Filesets can be filtered, which means the selected files will be used
+ as Velocity templates. They can be non-filtered, which means the selected
files will be copied without modification.
- Filesets can be packaged, which means the selected files will be
- generated/copied in a directory structure that is prepended by the package
- property. They can be non-packaged, which means that the selected files
+ Filesets can be packaged, which means the selected files will be
+ generated/copied in a directory structure that is prepended by the package
+ property. They can be non-packaged, which means that the selected files
will be generated/copied without that prepend.
A fileset is defined in the <<<archetype-metadata.xml>>> with this fragment:
@@ -148,16 +148,16 @@ How metadata on an archetype is stored?
...
+---
- This example shows a fileset that will select all the java files in the
- <<<src/test/java>>> directory of the archetype resources, except the
+ This example shows a fileset that will select all the java files in the
+ <<<src/test/java>>> directory of the archetype resources, except the
<<<AllTest.java>>> file that is located at the root of this directory.
- This filset also is packaged and filtered.
+ This filset is also packaged and filtered.
* Defining multi module in the archetype metadata
- Inner modules of an archetype are used to create a multi module Maven 2
+ Inner modules of an archetype are used to create a multi-module Maven 2
project from a single archetype.
Modules in the <<<archetype-metadata.xml>>> file are defined like:
@@ -177,28 +177,28 @@ How metadata on an archetype is stored?
</archetype-descriptor>
+---
- In the example above, the archetype <<<multi-module>>> contains a module
- named <<<SubProject>>>. This module is located in the <<<sub-project>>>
+ In the example above, the archetype <<<multi-module>>> contains a module
+ named <<<SubProject>>>. This module is located in the <<<sub-project>>>
directory of the archetype. It also has the artifactId <<<subproject>>>.
- The attributes name, id and dir of the module are used to determine the
- directory where to generate that module's files, they also are used to
- determine the artifactId of the Maven 2 project corresponding to this
+ The attributes name, id and dir of the module are used to determine the
+ directory where to generate that module's files, they also are used to
+ determine the artifactId of the Maven 2 project corresponding to this
module.
* Putting it all together
- The <<<\<requiredProperties\>>>> element is only allowed as a child of
+ The <<<\<requiredProperties\>>>> element is only allowed as a child of
<<<\<archetype-descriptor\>>>>.
- Modules are allowed in <<<\<archetype-descriptor\>>>> and in <<<\<modules\>>>> (no limit is
+ Modules are allowed in <<<\<archetype-descriptor\>>>> and in <<<\<modules\>>>> (no limit is
given).
- <<<\<archetype-descriptor\>>>> and <<<\<modules\>>>> must define at least one <<<\<fileSet\>>>> each to
+ <<<\<archetype-descriptor\>>>> and <<<\<modules\>>>> must define at least one <<<\<fileSet\>>>> each to
be valid.
- It is possible to define default values for required properties by
+ It is possible to define default values for required properties by
defining say the groupId and giving it a default:
+---
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/archetype.apt Sun Mar 21 14:10:52 2010
@@ -29,25 +29,25 @@
What is an archetype?
-* A Maven 2 project 'en devenir'
+* A Maven 2 project 'en devenir'
- I.e. an abstract representation of a kind of project
- that can be instantiated into a concrete customised
- Maven 2 project.
+ I.e. an abstract representation of a kind of project
+ that can be instantiated into a concrete customised
+ Maven 2 project.
- An archetype knows which files will be part of the
- instantiated project and which properties to fill
- to properly customise the project.
-
- Each archetype defines a set of common properties:
+ An archetype knows which files will be part of the
+ instantiated project and which properties to fill
+ to properly customise the project.
- * groupId which will be the groupId of the project
+ Each archetype defines a set of common properties:
- * artifactId which will be the artifactId of the project
+ * <<<groupId>>> which will be the groupId of the project
- * version which will be the version of the project
+ * <<<artifactId>>> which will be the artifactId of the project
- * package which will be the base package of all source files of the project
+ * <<<version>>> which will be the version of the project
+
+ * <<<package>>> which will be the base package of all source files of the project
[]
@@ -55,7 +55,7 @@ What is an archetype?
* A jar file
- The minimal content of the jar file:
+ The minimal content of the jar file is:
+---
.
@@ -67,14 +67,14 @@ What is an archetype?
`-- pom.xml [3]
+---
- [[1]] The metadata file that defines:
+ [[1]] The metadata file that defines:
- * the default values of the common properties,
+ * the default values of the common properties,
- * a set of additional properties with their default values,
+ * a set of additional properties with their default values,
* a set of archetype resources;
-
+
[]
[[2]] The resource files defined by the archetype metadata,
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/create-from-project.apt Sun Mar 21 14:10:52 2010
@@ -31,35 +31,34 @@ What is done during the creation of an a
* Property resolution
- First the Archetype Plugin asks the user to provide the common properties'
- values (archetype.groupId, archetype.artifactId, archetype.version, groupId,
- artifactId, version, package).
+ First, the Archetype Plugin asks the user to provide the common properties'
+ values (<<<archetype.groupId>>>, <<<archetype.artifactId>>>, <<<archetype.version>>>,
+ <<<groupId>>>, <<<artifactId>>>, <<<version>>>, <<<package>>>).
Then it asks for additional properties.
* Archetype creation
- Using the project's directory as sources, the properties filteredExtensions
- and languages, the module tree; the Archetype Plugin search for revelant
+ Using the project's directory as sources, <<<filteredExtensions>>> and <<<languages>>>
+ properties, the module tree; the Archetype Plugin searches for revelant
filesets indexed by module.
- Using the revelant filesets, the module tree, the resolved properties; the
+ Using the revelant filesets, the module tree, the resolved properties; the
Archetype Plugin creates the archetype's resources.
- Then it creates the archetype's descriptor using the the module tree, the
- revelant filesets, the resolved properties.
+ Then it creates the archetype's descriptor.
Finishing by creating the pom for the archetype as a project.
* Archetype installation
- Optionally after creating the archetype, the Archetype Plugin installs the
+ Optionally, after creating the archetype, the Archetype Plugin installs the
archetype in the local repository. And it updates the local catalog.
* Archetype deployment
- Optionally after installing the archetype, the Archetype Plugin deploys the
- archetype in the remote repository.
+ Optionally, after installing the archetype, the Archetype Plugin deploys the
+ archetype to the remote repository.
* Interactive mode
@@ -68,16 +67,16 @@ What is done during the creation of an a
* Advanced batch mode
- The additional properties in batch mode can only be defined using a property
- file. This file also can contain the other properties both the commons and
- the filteredExtensions and languages.
+ In batch mode, the additional properties can only be defined using a property
+ file. This file can also contain the other properties, both the commons and
+ <<<filteredExtensions>>> and <<<languages>>>.
* Fileset resolution
- In each module's directory and excluding submodules trees, the Archetype
- Plugin sorts the files by languages, fileteredExtensions and sensible
- default base pathes (src/main/<languages>, src/main/<siblings>,
+ In each module's directory and excluding submodules trees, the Archetype
+ Plugin sorts the files by languages, fileteredExtensions and sensible
+ default base pathes (src/main/<languages>, src/main/<siblings>,
src/test/<languages>, src/test/<siblings>, ...).
- This defines a tri-dimensional matrix. Each sorted group (matrix' cases)
+ This defines a tri-dimensional matrix. Each sorted group (matrix' cases)
becomes a resolved fileset.
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/generate.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/generate.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/generate.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/generate.apt Sun Mar 21 14:10:52 2010
@@ -29,80 +29,81 @@
What is done during the creation of a project?
-* Archetype selection
+* Archetype selection
- First the Archetype Plugin asks the user to select an archetype from a list
+ First, the Archetype Plugin asks the user to select an archetype from a list
of known archetypes. Archetypes are known using archetype catalogs.
* Archetype configuration
- Then the Archetype Plugin ask the user to provide values for each of the
- four main required properties. Which are the project's groupId, artifactId,
- version and package.
+ Then the Archetype Plugin asks the user to provide values for each of the
+ four main required properties, which are the project's groupId, artifactId,
+ version and package.
It also ask for values of the additional required properties defined in the
archetype's metadata file.
* Project generation
- Finally, the Archetype Plugin generates the Maven 2 project from the
+ Finally, the Archetype Plugin generates the Maven 2 project from the
selected/configured archetype.
- The archetype used to generate the project can be single or multi module.
+ The archetype used to generate the project can be single or multi-module.
- The archetype used to generate the project can be partial, which means it
+ The archetype used to generate the project can be partial, which means it
enhances an existing project instead of creating a new one.
- If the Archetype Plugin is called from an existing project, using a
- complete (not partial) archetype, then it generates a sub module in the
+ If the Archetype Plugin is called from an existing project, using a
+ complete (not partial) archetype, then it generates a sub module in the
existing project.
- If the Archetype Plugin is configured to create a project in an existing
- directory, it first check for the existence of a <<<pom.xml>>> file before
+ If the Archetype Plugin is configured to create a project in an existing
+ directory, it first checks for the existence of a <<<pom.xml>>> file before
failing the generation.
* Batch mode
- It is possible to call the Archetype Plugin to generate project in batch
- mode (to get rid of the prompting). This is achieved by providing the
+ It is possible to call the Archetype Plugin to generate project in batch
+ mode (to get rid of the prompting). This is achieved by providing the
Archetype Plugin with all the needed values as system properties.
* <<<archetypeCatalog>>> which defaults to internal specifies the catalog(s)
- The valid catalogs are: internal (the default), local, remote, file://path, http://url.
+ The valid catalogs are: <<<internal>>> (the default), <<<local>>>, <<<remote>>>,
+ <<<file://path>>>, <<<http://url>>>.
- * <<<internal>>> uses an internal catalog
+ * <<<internal>>> uses an internal catalog
- * <<<local>>> uses the ~/.m2/archetype-catalog.xml file
+ * <<<local>>> uses the <<<~/.m2/archetype-catalog.xml>>> file
- * <<<remote>>> uses the http://repo1.maven.org/maven2/archetype-catalog.xml
- file
+ * <<<remote>>> uses the <<<http://repo1.maven.org/maven2/archetype-catalog.xml>>>
+ file
- * <<<file://path>>> uses the catalog file defined by path (or the
- <<<archetype-catalog.xml>>> file located in path directory)
+ * <<<file://path>>> uses the catalog file defined by path (or the
+ <<<archetype-catalog.xml>>> file located in path directory)
- * <<<http://url>>> uses the catalog file defined by url (or the
+ * <<<http://url>>> uses the catalog file defined by url (or the
<<<archetype-catalog.xml>>> file located in url web directory)
[]
-
+
* <<<archetypeGroupId>>> specifies the groupId of the archetype to use
-
+
* <<<archetypeArtifactId>>> specifies the artifactId of the archetype to use
-
+
* <<<archetypeVersion>>> specifies the version of the archetype to use
-
+
* <<<archetypeRepository>>> specifies the repository in which the archetype
resides
-
+
* <<<groupId>>> specifies the groupId of the generated project
-
+
* <<<artifactId>>> specifies the artifactId of the generated project
-
+
* <<<version>>> specifies the version of the generated project
-
- * <<<package>>> specifies the package for the sources of the generated
+
+ * <<<package>>> specifies the package for the sources of the generated
project
-
+
* <<<anotherVelocityProperty>>> specifies any other required property
[]
Modified: maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt
URL: http://svn.apache.org/viewvc/maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt?rev=925768&r1=925767&r2=925768&view=diff
==============================================================================
--- maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt (original)
+++ maven/archetype/trunk/archetype-plugin/src/site/apt/specification/specification.apt Sun Mar 21 14:10:52 2010
@@ -34,16 +34,16 @@ Specification
* {{{archetype.html}What is an archetype?}}
- * {{{archetype-metadata.html}How metadata on an archetype is stored?}}
+ * {{{archetype-metadata.html}How is metadata on an archetype stored?}}
* {{{generate.html}What is done during the creation of a project?}}
- * {{{archetype-catalog.html}How the Archetype Plugin know about archetype?}}
+ * {{{archetype-catalog.html}How does the Archetype Plugin know about archetype?}}
* {{{create-from-project.html}What is done during the creation of an archetype?}}
~~
-~~ * {{{update-catalog.html}How the Archetype Plugin know about new archetypes?}}
+~~ * {{{update-catalog.html}How does the Archetype Plugin know about new archetypes?}}
~~
-~~ * {{{crawl-repository.html}How archetype lists are created?}}
+~~ * {{{crawl-repository.html}How are archetype lists created?}}
[]
\ No newline at end of file