IVY-1651: improved documentation regarding patterns and retrieve task

2024-11-17 12:28:43 +01:00 · 2024-11-17 12:28:43 +01:00 · 0e83732542
parent 6d0e0aa57a
commit 0e83732542
11 changed files with 28 additions and 22 deletions
--- a/asciidoc/concept.adoc
+++ b/asciidoc/concept.adoc
@ -117,6 +117,10 @@ the configuration name
 (*__since 1.4__*) +
 the original artifact name (not including the extension)

+`[classifier]`::
+(*__since 1.4__*) +
+the artifact classifier for Maven dependencies
+
 The difference between type and extension is explained in the Ivy file documentation.

 (*__since 1.2__*) `[organization]` can be used instead of `[organisation]`.
--- a/asciidoc/release-notes.adoc
+++ b/asciidoc/release-notes.adoc
@ -45,6 +45,7 @@ For details about the following changes, check our JIRA install at link:https://
 - FIX: trying to set safe XML features causes SAXExceptions when used with certain XML parsers (jira:IVY-1647[])
 - FIX: some unit tests failed on Java 8 (jira:IVY-1648[]) (Thanks to Adrien Piquerez)
 - FIX: cached Ivy files were not valid in some scenarios (jira:IVY-1649[], jira:IVY-1650[]) (Thanks to Moritz Baumann)
+- DOCUMENTATION: improved to the documentation regarding the use of patterns in the resolvers and retrieve task (jira:IVY-1651[]) (Thanks to Lewis John McGibbney)

 ////
 Samples :
@ -119,6 +120,7 @@ Here is the list of people who have contributed source code and documentation up
 * Mitch Gitman
 * Evgeny Goldin
 * Scott Goldstein
+* Jason A. Guild
 * Stephen Haberman
 * Aaron Hachez
 * Ben Hale
@ -141,6 +143,7 @@ Here is the list of people who have contributed source code and documentation up
 * Heschi Kreinick
 * Sebastian Krueger
 * Thomas Kurpick
+* Berno Langer
 * Costin Leau
 * Ilya Leoshkevich
 * Tat Leung
@ -151,6 +154,7 @@ Here is the list of people who have contributed source code and documentation up
 * Sakari Maaranen
 * Jan Materne
 * Markus M. May
+* Lewis John McGibbney
 * Abel Muino
 * J. Lewis Muir
 * Stephen Nesbitt
@ -212,5 +216,3 @@ Here is the list of people who have contributed source code and documentation up
 * Jaroslaw Wypychowski
 * Sven Zethelius
 * Aleksey Zhukov
-* Jason A. Guild
-* Berno Langer
--- a/asciidoc/resolver/filesystem.adoc
+++ b/asciidoc/resolver/filesystem.adoc
@ -72,9 +72,9 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
-|m2compatible|True if this resolver should be Maven 2 compatible, false otherwise (*__since 1.3__*)|No, defaults to false
+|m2compatible|True if this resolver should be Maven 2 compatible, false otherwise (*__since 1.3__*).|No, defaults to false
 |local|True if this resolver should be considered local, false otherwise (*__since 1.4__*). See useOrigin attribute on the link:../settings/caches{outfilesuffix}[caches] element for details.|No, defaults to true
-|transactional|true to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible (*__since 2.0__*). See above for details.|No, defaults to auto
+|transactional|True to force the use of transaction, false to prevent the use of transaction, auto to get transaction when possible (*__since 2.0__*). See above for details.|No, defaults to auto
 |=======


@ -84,6 +84,6 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======
--- a/asciidoc/resolver/jar.adoc
+++ b/asciidoc/resolver/jar.adoc
@ -53,8 +53,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/mirrored.adoc
+++ b/asciidoc/resolver/mirrored.adoc
@ -50,8 +50,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/packager.adoc
+++ b/asciidoc/resolver/packager.adoc
@ -82,8 +82,8 @@ Configure a resourceURL in situations where you don't want to rely on (or wait f
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|Defines a pattern for ivy.xml files, using the pattern attribute|1..n
-|artifact|Defines a pattern for packager.xml files, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/sftp.adoc
+++ b/asciidoc/resolver/sftp.adoc
@ -70,8 +70,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/ssh.adoc
+++ b/asciidoc/resolver/ssh.adoc
@ -59,8 +59,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/url.adoc
+++ b/asciidoc/resolver/url.adoc
@ -49,8 +49,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/resolver/vfs.adoc
+++ b/asciidoc/resolver/vfs.adoc
@ -41,8 +41,8 @@ This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common
 [options="header"]
 |=======
 |Element|Description|Cardinality
-|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
-|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
+|ivy|Defines a link:../concept{outfilesuffix}#patterns[pattern] for Ivy files, using the pattern attribute.|0..n
+|artifact|Defines a link:../concept{outfilesuffix}#patterns[pattern] for artifacts, using the pattern attribute.|1..n
 |=======


--- a/asciidoc/use/retrieve.adoc
+++ b/asciidoc/use/retrieve.adoc
@ -35,8 +35,8 @@ For instance, for the pattern `lib/[conf]/[artifact].[ext]`, the root will be `l
 [options="header",cols="15%,50%,35%"]
 |=======
 |Attribute|Description|Required
-|pattern|the pattern to use to copy the dependencies|No. Defaults to `${ivy.retrieve.pattern}`
-|ivypattern|the pattern to use to copy the Ivy files of dependencies (*__since 1.3__*)|No. Dependency Ivy files are not retrieved by default.
+|pattern|The link:../concept{outfilesuffix}#patterns[pattern] to use to copy the dependencies. Make sure to specify a pattern that defines unique filenames for the artifacts.|No. Defaults to `${ivy.retrieve.pattern}`
+|ivypattern|the link:../concept{outfilesuffix}#patterns[pattern] to use to copy the Ivy files of dependencies (*__since 1.3__*)|No. Dependency Ivy files are not retrieved by default.
 |conf|a comma separated list of the configurations to retrieve|No. Defaults to the configurations resolved by the last resolve call, or `$$*$$` if no resolve was explicitly called
 |sync|`true` to synchronize the destination, false to just make a copy (*__since 1.4__*)|No. Defaults to `false`
 |type|comma separated list of accepted artifact types (*__since 1.4__*)|No. All artifact types are accepted by default.