clarify repository id used for downloading the actual archetype file

maven-archetype-plugin/src/main/java/org/apache/maven/archetype/mojos/CreateProjectFromArchetypeMojo.java

@@ -88,8 +88,7 @@ public class CreateProjectFromArchetypeMojo extends AbstractMojo implements Cont
 
     /**
      * The archetype catalogs to use to build a list and let the user choose from.
-     * It is a comma separated list of catalogs.
-     * Catalogs use the following schemes:
+     * It is a comma-separated list of one or more of the following catalog schemes
      * <ul>
      * <li><code>local</code> which is the shortcut to the local repository</li>
      * <li><code>remote</code> which is the shortcut for a repository with id {@code archetype},
@@ -98,9 +97,9 @@ public class CreateProjectFromArchetypeMojo extends AbstractMojo implements Cont
      * <li><code>internal</code> which is an <a href="https://maven.apache.org/archetype/archetype-common/internal.html">internal catalog</a></li>
      * </ul>
      * <p/>
-     * If you want the catalogs to come from a different repository, please add
+     * If you want the catalog to come from a custom repository, please add
      * a dedicated repository with id {@code archetype} and optionally a server section with the same id to
-     * your {@code settings.xml}
+     * your {@code settings.xml} and use the catalog scheme <code>remote</code>.
      * <pre>
      *   &lt;repository&gt;
      *     &lt;id&gt;archetype&lt;/id&gt;
@@ -114,10 +113,12 @@ public class CreateProjectFromArchetypeMojo extends AbstractMojo implements Cont
      *     &lt;password&gt;s3cr3t&lt;/password&gt;
      *   &lt;/server&gt;
      * </pre>
+     * In order to use that repository <em>only</em> for resolving the catalog (and not for downloading regular Maven dependencies from it) it is recommended to
+     * <a href="https://maven.apache.org/settings.html#profiles">conditionally include the repository in a profile activated through a property</a>.
      *
      * In case of mirrors for either repository {@code archetype} or {@code central} the <a href="https://maven.apache.org/guides/mini/guide-mirror-settings.html">matching mirror's id</a> is considered
      * for server settings (like authentication).
-     * If the Maven Central repository catalog file is empty, <code>internal</code> catalog is used instead.
+     * If the repository's catalog file is empty or cannot be retrieved, <code>internal</code> catalog is transparently used as fallback.
      */
     @Parameter(property = "archetypeCatalog", defaultValue = "remote,local")
     private String archetypeCatalog;

maven-archetype-plugin/src/site/fml/faq.fml

@@ -37,11 +37,14 @@ under the License.
     <faq id="authentication">
       <question>How to generate a project from an archetype in a custom (potentially authenticated) repository?</question>
       <answer>
-        <p>The server/repository id used to download the artifact is <code>archetype</code>: You have to
+        <p>The server/repository id used to download the <strong>catalog</strong> is <code>archetype</code>: You have to
         <a href="/settings.html#Servers">define corresponding server configuration and repository in
-        <code>settings.xml</code></a> with this id. 
+        <code>settings.xml</code></a> with this id to generate a project based on the catalog
         In case of <a href="/guides/mini/guide-mirror-settings.html">mirroring</a> the mirror id of that mirror which
-        matches repository id <code>archetype</code> or <code>central</code> is used for authentication.</p>
+        matches repository id <code>archetype</code> or <code>central</code> is used for authentication.
+        For the actual resolving of the <strong>actual archetype</strong> an artificial repository with id <code>&lt;archetype-artifactId&gt;-repo</code> is used in case
+        the underlying <a href="/archetype/archetype-models/archetype-catalog/archetype-catalog.html">Archetype Catalog Item</a> contained a repository (leveraging its URL).
+        As fallback all regular remote repositories (as defined in the <code>settings.xml</code>) are tried.</p>
       </answer>
     </faq>