Update documentation regarding archetypeCatalog and archetype repositories
diff --git a/maven-archetype-plugin/src/it/mrm/settings.xml b/maven-archetype-plugin/src/it/mrm/settings.xml
index 5913350..bcae17c 100644
--- a/maven-archetype-plugin/src/it/mrm/settings.xml
+++ b/maven-archetype-plugin/src/it/mrm/settings.xml
@@ -1,5 +1,4 @@
<?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
diff --git a/maven-archetype-plugin/src/site/apt/archetype-repository.apt b/maven-archetype-plugin/src/site/apt/archetype-repository.apt
new file mode 100644
index 0000000..a9a2c83
--- /dev/null
+++ b/maven-archetype-plugin/src/site/apt/archetype-repository.apt
@@ -0,0 +1,81 @@
+ ------
+ Archetype Repository
+ ------
+ Robert Scholte
+ ------
+ 2017-04-01
+ ------
+
+~~ 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.
+
+~~ NOTE: For help with the syntax of this file, see:
+~~ http://maven.apache.org/doxia/references/apt-format.html
+
+ As of Maven Archetype Plugin 3.0.0 the archetype resolution has changed. It is not possible anymore to specify
+ the repository via the commandline, but instead the repositories as already specified for Maven are used.
+ This means that also the mirrors and proxies are respected, as well as the authentication on repositories.
+
+ If you're not using a repository manager and the archetype is available at Maven Central, there's nothing you have to do.
+
+ If you're using a repository manager and the archetype is available via this manager, there's nothing you have to do.
+
+ Only in case of a third party archetype which is not managed by a repository you have to add a repository entry to your <<<settings.xml>>> once:
+
+---
+<settings>
+ <mirrors>
+ <mirror>
+ <id>mrm-maven-plugin</id>
+ <name>Mock Repository Manager</name>
+ <url>http://www.mycompany.com/maven-reporistory-manager</url>
+ <mirrorOf>*,!archetype</mirrorOf>
+ </mirror>
+ </mirrors>
+
+ <!--
+ <servers>
+ <server>
+ <id>archetype</id>
+ <username/>
+ <password/>
+ </server>
+ </servers>
+ -->
+
+ <profiles>
+ <profile>
+ <id>acme</id>
+ <repositories>
+ <repository>
+ <id>archetype</id>
+ <url>https://www.acme.com/repo</url>
+ <releases>
+ <enabled>true</enabled>
+ <checksumPolicy>fail</checksumPolicy>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ <checksumPolicy>warn</checksumPolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+ </profile>
+ </profiles>
+</settings>
+---
+
diff --git a/maven-archetype-plugin/src/site/apt/examples/generate-alternative-catalog.apt b/maven-archetype-plugin/src/site/apt/examples/generate-alternative-catalog.apt
index 585e398..242eecf 100644
--- a/maven-archetype-plugin/src/site/apt/examples/generate-alternative-catalog.apt
+++ b/maven-archetype-plugin/src/site/apt/examples/generate-alternative-catalog.apt
@@ -37,19 +37,13 @@
* <<<remote>>> to use the maven's remote catalog. No catalog is currently provided.
- * <<<file://path/to/archetype-catalog.xml>>> to use a specific local catalog.
- When the catalog file is named <<<archetype-catalog.xml>>>, it can be omitted.
-
- * <<<http://url/to/archetype-catalog.xml>>> to use a specific remote catalog.
- When the catalog file is named <<<archetype-catalog.xml>>>, it can be omitted.
-
[]
The default value is <<<remote,local>>>. Thus the local catalog is shown
just after the remote one.
+--
-$ mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org
+$ mvn archetype:generate
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
diff --git a/maven-archetype-plugin/src/site/apt/specification/generate.apt b/maven-archetype-plugin/src/site/apt/specification/generate.apt
index 41a605f..eae9c58 100644
--- a/maven-archetype-plugin/src/site/apt/specification/generate.apt
+++ b/maven-archetype-plugin/src/site/apt/specification/generate.apt
@@ -68,22 +68,15 @@
Archetype Plugin with all the needed values as system properties.
* <<<archetypeCatalog>>> which 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>>>.
* <<<internal>>> uses an internal catalog
- * <<<local>>> uses the <<<~/.m2/archetype-catalog.xml>>> file
+ * <<<local>>> uses the <<<archetype-catalog.xml>>> file from the local repository
- * <<<remote>>> uses the <<<http://repo.maven.apache.org/maven2/archetype-catalog.xml>>>
+ * <<<remote>>> uses the <<<archetype-catalog.xml>>> from Maven Central, either direct or via a repository manager
file
- * <<<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
- <<<archetype-catalog.xml>>> file located in URL directory)
-
[]
* <<<archetypeGroupId>>> specifies the groupId of the archetype to use
diff --git a/maven-archetype-plugin/src/site/apt/usage.apt b/maven-archetype-plugin/src/site/apt/usage.apt
index 5651cd2..0e822df 100644
--- a/maven-archetype-plugin/src/site/apt/usage.apt
+++ b/maven-archetype-plugin/src/site/apt/usage.apt
@@ -32,6 +32,8 @@
Project creation
Creating a project from an archetype involves three steps:
+
+ * prepare repository reference
* the selection of the archetype,
@@ -43,6 +45,12 @@
Usage
+ In general an archetype is coming from a remote repository. If that repository can
+ be reached via the setup of your Maven, you're ready to start. In cases where the
+ repository is not managed and you want to refer to it directly, you have to add the
+ repository to your <<<settings.xml>>>. Read the small set of instructions on the
+ {{{./archetype-repository.html}Archetype Repository}}-page.
+
Calling <<<archetype:generate>>> the plugin will first ask to choose
the archetype from the internal catalog. Just enter the number of the archetype.
diff --git a/maven-archetype-plugin/src/site/site.xml b/maven-archetype-plugin/src/site/site.xml
index bf44526..b6ada8c 100644
--- a/maven-archetype-plugin/src/site/site.xml
+++ b/maven-archetype-plugin/src/site/site.xml
@@ -39,6 +39,7 @@
<menu name="Reference">
<item name="Archetype Descriptor" href="../archetype-models/archetype-descriptor/archetype-descriptor.html"/>
<item name="maven-archetype Packaging" href="../archetype-packaging/"/>
+ <item name="Archetype repository" href="/archetype-repository.html"/>
</menu>
<menu name="Examples">
