[11/29] ant-ivy git commit: Initial auto-converted .adoc files from xooki2asciidoc convertor

[ja...@apache.org]

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/multiproject.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/multiproject.adoc b/asciidoc/tutorial/multiproject.adoc
new file mode 100644
index 0000000..8aa364b
--- /dev/null
+++ b/asciidoc/tutorial/multiproject.adoc
@@ -0,0 +1,298 @@
+
+In the previous tutorial, you saw how to deal with dependencies between two simple projects.
+
+This tutorial will guide you through the use of Ivy in a more complete environment. All of the code for this tutorial is available in the `src/example/multi-project` directory of the Ivy distribution.
+
+
+== Context
+
+Here is a 10000ft overview of the projects involved in this tutorial:
+
+
+* version +
+ helps to identify module by a version
+
+* list +
+ gives a list of files in a directory (recursively)
+
+* size +
+ gives the total size of all files in a directory, or of a collection of files
+
+* find +
+ find files in a given dir or among a list of files which match a given name
+
+* sizewhere +
+ gives the total size of files matching a name in a directory
+
+* console +
+ give access to all other modules features through a simple console app
+
+For sure this is not aimed to demonstrate how to develop a complex app or give indication of advanced algorithm :-)
+
+But this gives a simple understanding of how Ant+Ivy can be used to develop an application divided in multiple modules.
+
+Now, here is how these modules relate to each other:
+link:../samples/projects-dependencies-graph.jpg[image::../samples/projects-dependencies-graph-small.jpg[]__click to enlarge__]
+
+Modules in yellow are the modules described in this tutorial, and modules in blue are external dependencies (we will see how to generate this graph later in this tutorial).
+
+As you can see, we have here a pretty interesting set of modules with dependencies between each other, each depending on the latest version of the others.
+
+
+== The example files
+
+The sources for this tutorial can be found in `src/example/multi-project` in the Ivy distribution. In this directory, you will find the following files:
+
+
+* link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/build.xml[build.xml] +
+This is a root build file which can be used to call targets on all modules, in the order of their dependencies (ensuring that a module is always built before any module depending on it, for instance)
+
+* common
+<ul>
+<li>link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/common/common.xml[common.xml]</li> the common build file imported by all build.xml files for each project. This build defines the targets which can be used in all projects.
+<li>link:https://git-wip-us.apache.org/repos/asf?p=ant-ivy.git;a=blob;f=src/example/multi-project/common/build.properties[build.properties]</li>some properties common to all projects
+</ul>
+ +
+
+* projects +
+contains a directory per module, with each containing:
+<ul>
+
+* ivy.xml +
+Ivy file of the module, describing its dependencies upon other modules and/or external modules.
+Example:
+
+[source]
+----
+
+<ivy-module version="1.0">
+    <info 
+        organisation="org.apache.ivy.example"
+        module="find"
+        status="integration"/>
+    <configurations>
+      <conf name="core"/>
+      <conf name="standalone" extends="core"/>
+    </configurations>
+    <publications>
+      <artifact name="find" type="jar" conf="core" />
+    </publications>
+    <dependencies>
+      <dependency name="version" rev="latest.integration" conf="core->default" />
+      <dependency name="list" rev="latest.integration" conf="core" />
+      <dependency org="commons-collections" name="commons-collections" rev="3.1" conf="core->default" />
+      <dependency org="commons-cli" name="commons-cli" rev="1.0" conf="standalone->default" />
+    </dependencies>
+</ivy-module>
+
+----
+
+
+* build.xml +
+The build file of the project, which consists mainly of an import of the common build file and of a module specific properties file:
+
+[source]
+----
+
+<project name="find" default="compile">
+	<property file="build.properties"/>
+	
+	<import file="${common.dir}/common.xml"/>
+</project>
+
+----
+
+
+* build.properties +
+Module specific properties + properties to find the common build file
+
+[source]
+----
+
+projects.dir = ${basedir}/..
+wkspace.dir = ${projects.dir}/..
+common.dir = ${wkspace.dir}/common
+
+----
+
+
+* src +
+ the source directory with all java sources
+
+</ul>
+
+Note that this example doesn't demonstrate many good practices for software development in general, in particular you won't find any unit test in these samples, even if we think unit testing is very important. But this isn't the aim of this tutorial.
+
+Now that you are a bit more familiar with the structure, let's have a look at the most important part of this example: the common build file. Indeed, as you have seen, all the module's build files only import the common build file, and define their dependencies in their ivy files (which you should begin to be familiar with).
+
+So, here are some aspects of this common build file:
+
+=== ivy settings
+
+
+[source]
+----
+
+<!-- setup ivy default configuration with some custom info -->
+<property name="ivy.local.default.root" value="${repository.dir}/local"/>
+<property name="ivy.shared.default.root" value="${repository.dir}/shared"/>
+
+<!-- here is how we would have configured ivy if we had our own ivysettings file
+<ivy:settings file="${common.dir}/ivysettings.xml" id="ivy.instance" />
+-->
+
+----
+
+This declaration configures Ivy by only setting two properties: the location for the local repository and the location for the shared repository. It's the only settings done here, since Ivy is configured by default to work in a team environment (see link:../tutorial/defaultconf.html[default settings tutorial] for details about this). For sure in a real environment, the shared repository location would rather be in a team shared directory (or in a more complex repository, again see the default settings tutorial to see how to use something really different).
+Commented out you can see how the settings would have been done if the default setting wasn't OK for our purpose.
+
+
+=== resolve dependencies
+
+
+[source]
+----
+
+<target name="resolve" depends="clean-lib, load-ivy" description="--> resolve and retrieve dependencies with ivy">
+    <mkdir dir="${lib.dir}"/> <!-- not usually necessary, ivy creates the directory IF there are dependencies -->
+    
+    <!-- the call to resolve is not mandatory, retrieve makes an implicit call if we don't -->
+    <ivy:resolve file="${ivy.file}"/>
+    <ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" />
+</target>
+
+----
+
+You should begin to be familiar with using Ivy this way. We call __resolve__ explicitly to use the ivy file configured (the default would have been fine), and then call __retrieve__ to copy resolved dependencies artifacts from the cache to a local lib directory. The pattern is also used to name the artifacts in the lib dir with their name and extension only (without revision), this is easier to use with an IDE, as the IDE configuration won't change when the artifacts version change.
+
+
+=== ivy-new-version
+
+
+[source]
+----
+
+<target name="ivy-new-version" depends="load-ivy" unless="ivy.new.revision">
+    <!-- default module version prefix value -->
+    <property name="module.version.prefix" value="${module.version.target}-dev-b" />
+    
+    <!-- asks Ivy for an available version number -->
+    <ivy:info file="${ivy.file}" />
+    <ivy:buildnumber 
+        organisation="${ivy.organisation}" module="${ivy.module}" 
+        revision="${module.version.prefix}" defaultBuildNumber="1" revSep=""/>
+</target>
+
+----
+
+This target is used to ask Ivy to find a new version for a module. To get details about the module we are dealing with, we pull information out of the ivy file by using the ivy:info task. Then the link:../use/buildnumber.html[buildnumber] task is used to get a new revision, based on a prefix we set with a property, by default it will be 1.0-dev-b (have a look at the default value for `module.version.target` in the `common/build.properties` file). Each module built by this common build file could easily override this by either setting a different `module.version.target` in its module specific `build.properties`, or even overriding `module.version.prefix`. To get the new revision, Ivy scans the repository to find the latest available version with the given prefix, and then increments this version by 1.
+
+
+=== publish
+
+
+[source]
+----
+
+<target name="publish" depends="clean-build, jar" description="--> publish this project in the ivy repository">
+    <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]" 
+                       resolver="shared"
+                       pubrevision="${version}" 
+                       status="release"
+    />
+    <echo message="project ${ant.project.name} released with version ${version}" />
+</target>
+
+----
+
+This target publishes the module to the shared repository, with the revision found in the version property, which is set by other targets (based on ivy-new-version we have seen above). It can be used when a module reaches a specific milestone, or whenever you want the team to benefit from a new version of the module.
+
+=== publish-local
+
+
+[source]
+----
+
+<target name="publish-local" depends="local-version, jar" description="--> publish this project in the local ivy repository">
+    <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]" 
+                    resolver="local"
+                    pubrevision="${version}"
+                    pubdate="${now}"
+                    status="integration"
+                    forcedeliver="true"
+    />
+    <echo message="project ${ant.project.name} published locally with version ${version}" />
+</target>
+
+----
+
+This is very similar to the publish task, except that this publishes the revision to the local repository, which is used only in your environment and doesn't disturb the team. When you change something in a module and want to benefit from the change in another one, you can simply call `publish-local` in this module, and then your next build of the other module will automatically get this local version.
+
+=== clean-local
+
+
+[source]
+----
+
+<target name="clean-local" description="--> cleans the local repository for the current module">
+   <delete dir="${ivy.local.default.root}/${ant.project.name}"/>
+</target>
+
+----
+
+This target is used when you don't want to use your local version of a module anymore. For example, when you release a new version to the whole team, or discard your local changes and want to take advantage of a new version from the team.
+
+=== report
+
+
+[source]
+----
+
+<target name="report" depends="resolve" description="--> generates a report of dependencies">
+    <ivy:report todir="${build.dir}"/>
+</target>
+
+----
+
+Generates both an html report and a graphml report.
+
+For example, to generate a graph like the one shown at the beginning of this tutorial, you just have to follow the instructions given link:../yed.html[here] with the graphml file you will find in 
+[source]
+----
+projects/console/build/
+----
+
+after having called report in the console project, and that's it, you have a clear overview of all your app dependencies!
+
+
+== Playing with the projects
+
+You can play with this tutorial by using regular Ant commands. Begin in the base directory of the tutorial (src/example/multi-project), and run ant -p:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/multi-project-general-antp.txt[]
+
+----
+
+
+
+This gives you an idea of what you can do here. To make sure you have at least one version of all your modules published in your repository (required to build modules having dependencies on the others), you can run `ant publish-all` (example log link:log/multi-project-general-publishall.txt[here]).
+
+You will see that Ivy calls the publish target on all the modules, following the order of the dependencies, so that a dependee is always built and published before its depender. Feel free to make changes in the source code of a module (changing a method name for instance) and in the module using the method, then call publish-all to see how the change in the dependee is compiled first, published, and then available to the depender which can compile successfully.
+
+Then you can go in one of the example project directories (like projects/find for instance), and run `ant -p`:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/multi-project-find-antp.txt[]
+
+----
+
+
+
+You can see the targets available, thanks to the import of the `common.xml` build file. Play with the project by calling resolve, and publish, and see what happens when you do the same in other projects. An interesting thing to do for instance, is to change the dependencies of a project. If the module version now depends on a new commons library, you will see that all other projects depending on that version will get this library as part of their transitive dependencies once the new revision of the version project is published. Very easy! And if a project introduces a change with which the depender isn't compatible with yet, you can easily change the dependency in the depender to move from `latest.integration` to a fixed version with which the depender is compatible (probably the latest before the change). Keeping your modules under control is now very easy!
+
+By now, you should be pretty familiar with multi-project development with Ivy. We hope you will appreciate its power and flexibility! And these tutorials are only the beginning of your journey with Ivy, browse the link:../reference.html[reference documentation] to learn more about the features, subscribe to the mailing lists to share your experience and ask questions with the community, browse the source code, open jira issues, submit patches, join in and help make Ivy the best of dependency management tools!
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/tutorial/start.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/tutorial/start.adoc b/asciidoc/tutorial/start.adoc
new file mode 100644
index 0000000..40fbf38
--- /dev/null
+++ b/asciidoc/tutorial/start.adoc
@@ -0,0 +1,109 @@
+
+In this tutorial, you will see one of the simplest ways to use Ivy. With no specific settings, Ivy uses the maven 2 repository to resolve the dependencies you declare in an Ivy file. Let's have a look at the content of the files involved. 
+
+_You'll find this tutorial's sources in the ivy distribution in the src/example/hello-ivy directory._
+
+
+== The ivy.xml file
+
+This file is used to describe the dependencies of the project on other libraries.
+Here is the sample: 
+
+[source]
+----
+
+<ivy-module version="2.0">
+    <info organisation="org.apache" module="hello-ivy"/>
+    <dependencies>
+        <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
+        <dependency org="commons-cli" name="commons-cli" rev="1.0"/>
+    </dependencies>
+</ivy-module>
+
+----
+
+The format of this file should pretty easy to understand, but let's give some details about what is declared here. First, the root element ivy-module, with the version attribute used to tell Ivy which version of Ivy this file uses. 
+
+Then there is an info tag, which is used to give information about the module for which we are defining dependencies. Here we define only the organization and module name. You are free to choose whatever you want for them, but we recommend avoiding spaces for both.
+
+Finally, the dependencies section lets you define dependencies. Here this module depends on two libraries: commons-lang and commons-cli. As you can see, we use the `org` and `name` attributes to define the organization and module name of the dependencies we need. The `rev` attribute is used to specify the version of the module you depend on. 
+
+To know what to put in these attributes, you need to know the exact information for the libraries you depend on. Ivy uses the maven 2 repository by default, so we recommend you use link:http://mvnrepository.com[mvnrepository.com] to look for the module you want. Once you find it, you will have the details on how to declare the dependency in a maven POM. For instance:
+
+[source]
+----
+
+<dependency>
+    <groupId>commons-lang</groupId>
+    <artifactId>commons-lang</artifactId>
+    <version>2.0</version>
+</dependency>
+
+----
+
+To convert this into an Ivy dependency declaration, all you have to do is use the groupId as organization, the artifactId as module name, and the version as revision. That's what we did for the dependencies in this tutorial, that is commons-lang and commons-cli. Note that having commons-lang and commons-cli as organization is not the best example of what the organization should be. It would be better to use org.apache, org.apache.commons or org.apache.commons.lang. However, this is how these modules are identified in the maven 2 repository, so the simplest way to get them is to use the details as is (you will see in link:../tutorial/build-repository.html[Building a repository] that you can use namespaces to redefine these names if you want something cleaner).
+
+If you want more details on what you can do in Ivy files, you can have a look at the link:../ivyfile.html[Ivy files reference documentation].
+
+== The build.xml file
+
+The corresponding build file contains a set of targets, allowing you to resolve dependencies declared in the Ivy file, to compile and run the sample code, produce a report of dependency resolution, and clean the cache or the project.
+You can use the standard "ant -p" to get the list of available targets. Feel free to have a look at the whole file, but here is the part relevant to dependency resolution:
+
+[source]
+----
+
+<project xmlns:ivy="antlib:org.apache.ivy.ant" name="hello-ivy" default="run">
+    
+    ...
+    
+    <!-- ================================= 
+          target: resolve              
+         ================================= -->
+    <target name="resolve" description="--> retrieve dependencies with ivy">
+        <ivy:retrieve />
+    </target>
+</project>
+
+----
+
+As you can see, it's very easy to call Ivy to resolve and retrieve dependencies: all you need if Ivy is properly link:../install.html[installed] is to define an XML namespace in your Ant file (xmlns:ivy="antlib:org.apache.ivy.ant"). Then all the link:../ant.html[Ivy ant tasks] will be available in this namespace.
+
+Here we use only one task: the link:../use/retrieve.html[retrieve] task. With no attributes, it will use default settings and look for a file named `ivy.xml` for the dependency definitions. That's exactly what we want, so we need nothing more than that.
+
+Note that in this case we define a `resolve` target and call the `link:../use/retrieve.html[retrieve]` task. This may sound confusing, actually the retrieve task performs a link:../use/resolve.html[resolve] (which resolves dependencies and downloads them to a cache) followed by a retrieve (a copy of those file to a local project directory). Check the link:../principle.html[How does it work ?] page for details about that.
+
+== Running the project
+
+OK, now that we have seen the files involved, let's run the sample to see what happens. Open a shell (or command line) window, and enter the `hello-ivy` example directory.
+Then, at the command prompt, run `ant`:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/hello-ivy-1.txt[]
+
+----
+
+
+
+== What happened ?
+
+Without any settings, Ivy retrieves files from the maven 2 repository. That's what happened here. 
+The resolve task has found the commons-lang and commons-cli modules in the maven 2 repository, identified that commons-cli depends on commons-logging and so resolved it as a transitive dependency. Then Ivy has downloaded all corresponding artifacts in its cache (by default in your user home, in a .ivy2/cache directory). Finally, the retrieve task copies the resolved jars from the ivy cache to the default library directory of the project: the lib dir (you can change this easily by setting the pattern attribute on the link:../use/retrieve.html[retrieve] task).
+
+You might say that the task took a long time just to write out a "Hello Ivy!" message. But remember that a lot of time was spent downloading the required files from the web. Let's try to run it again:
+
+[source,shell]
+----
+
+include::asciidoc/tutorial/log/hello-ivy-2.txt[]
+
+----
+
+
+Great! The cache was used, so no download was needed and the build was instantaneous.
+
+And now, if you want to generate a report detailing all the dependencies of your module, you can call the report target, and check the generated file in the build directory. You should obtain something looking like link:../samples/apache-hello-ivy-default.html[this].
+
+As you can see, using Ivy to resolve dependencies stored in the maven 2 repository is extremely easy. Now you can go on with the next tutorials to learn more about link:../tutorial/conf.html[how to use module configurations] which is a very powerful Ivy specific feature. Other tutorials are also available where you will learn how to use Ivy settings to leverage a possibly complex enterprise repository. It may also be a good time to start reading the link:../reference.html[reference documentation], and especially the introduction material which gives a good overview of Ivy. The link:../bestpractices.html[best practices] page is also a must read to start thinking about how to use Ant+Ivy to build a clean and robust build system.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/artifactproperty.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/artifactproperty.adoc b/asciidoc/use/artifactproperty.adoc
new file mode 100644
index 0000000..f9bfb77
--- /dev/null
+++ b/asciidoc/use/artifactproperty.adoc
@@ -0,0 +1,57 @@
+
+*__since 1.1__*
+Sets an ant property for each dependency artifacts previously resolved.
+
+*__since 2.0__* This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+Please prefer the use of retrieve + standard ant path creation, which make your build more independent from ivy (once artifacts are properly retrieved, ivy is not required any more).
+
+The property name and value are generated using the classical pattern concept, all artifact tokens and ivy variables being available.
+
+*__since 2.0__* This tag will follow the ant usual behavior for properties.  If a property of the same name already exist, it's value will be unchanged.  This behavior can be changed using the 'overwrite' attribute.
+__WARNING : Before 2.0, the behavior was to overwrite the properties.  Since 2.0, the default is to not overwrite to properties__
+
+
+
+== Attributes
+
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|name|a pattern used to generate the name of the properties to set|Yes
+|value|a pattern used to generate the value of the properties to set|Yes
+|conf|a comma separated list of the configurations for which properties should be set|No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
+|haltonfailure|true to halt the build on ivy failure, false to continue|No. Defaults to true
+|validate|true to force ivy files validation against ivy.xsd, false to force no validation|No. Defaults to default ivy value (as configured in configuration file)
+|settingsRef|A reference to the ivy settings that must be used by this task *(since 2.0)*|No, 'ivy.instance' is taken by default.
+|overwrite|Overwrite the value of the property if it already exist *(since 2.0)*.  Before 2.0, the properties were always overwritten.|No, 'false' by default.
+|=======
+
+
+
+== Example
+
+Suppose we have one dependency called __mydep__ in revision 1.0 publishing two artifacts: __foo.jar__ and __bar.jar__.
+Then:
+
+[source]
+----
+
+<artifactproperty conf="build" 
+       name="[module].[artifact]-[revision]" 
+       value="${cache.dir}/[module]/[artifact]-[revision].[ext]"/>
+
+----
+
+will set two properties:
+
+[source]
+----
+
+mydep.foo-1.0 = my/cache/dir/mydep/foo-1.0.jar
+mydep.bar-1.0 = my/cache/dir/mydep/bar-1.0.jar
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/artifactreport.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/artifactreport.adoc b/asciidoc/use/artifactreport.adoc
new file mode 100644
index 0000000..5dde634
--- /dev/null
+++ b/asciidoc/use/artifactreport.adoc
@@ -0,0 +1,82 @@
+
+*__since 1.4__*
+The artifactreport task generates an xml report of all artifacts dependencies resolved by the last link:../use/resolve.html[resolve] task call during the same build.
+
+*__since 2.0__* This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+This report is different from the standard link:../use/report.html[report] which reports all modules and artifacts, whle this report is much simpler and focuses only on artifacts, and gives more information on artifacts, such as the original location and the retrieve location. 
+
+It is thus easy to use to generate things like a classpath file for an IDE.
+
+See this link:http://www.jaya.free.fr/ivy/doc/articles/ease-multi-module.html[article by Johan Stuyts] (who contributed this task) to see how he uses this task.
+
+Here is an example of generate file:
+
+[source]
+----
+
+<?xml version="1.0" encoding="UTF-8"?>
+<modules>
+  <module organisation="hippo" name="sant-classes" rev="1.01.00b04-dev" status="integration">
+    <artifact name="sant-classes-src" ext="zip" type="zip">
+      <origin-location is-local="true">
+        C:/home/jstuyts/data/ivy/local/hippo/sant-classes/1.01.00b04-dev/sant-classes-src-1.01.00b04-dev.zip</origin-location>
+      <cache-location>
+        C:/home/jstuyts/data/ivy/cache/hippo/sant-classes/zips/sant-classes-src-1.01.00b04-dev.zip</cache-location>
+      <retrieve-location>lib/test/sant-classes-src-1.01.00b04-dev.zip</retrieve-location>
+    </artifact>
+    <artifact name="sant-classes-unoptimized" ext="jar" type="jar">
+      <origin-location is-local="true">
+        C:/home/jstuyts/data/ivy/local/hippo/sant-classes/1.01.00b04-dev/sant-classes-unoptimized-1.01.00b04-dev.jar</origin-location>
+      <cache-location>
+        C:/home/jstuyts/data/ivy/cache/hippo/sant-classes/jars/sant-classes-unoptimized-1.01.00b04-dev.jar</cache-location>
+      <retrieve-location>lib/test/sant-classes-unoptimized-1.01.00b04-dev.jar</retrieve-location>
+    </artifact>
+  </module>
+  <module organisation="testng" name="testng" rev="4.6.1-jdk15" status="release">
+    <artifact name="testng" ext="jar" type="jar">
+      <origin-location is-local="false">
+        http://repository.hippocms.org/maven/testng/jars/testng-4.6.1-jdk15.jar</origin-location>
+      <cache-location>C:/home/jstuyts/data/ivy/cache/testng/testng/jars/testng-4.6.1-jdk15.jar</cache-location>
+      <retrieve-location>lib/test/testng-4.6.1-jdk15.jar</retrieve-location>
+    </artifact>
+  </module> 
+
+----
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|tofile|the file to which the report should be written|Yes
+|pattern|the retrieve pattern to use to fill the retrieve location information about the artifacts|No. Defaults to ${ivy.retrieve.pattern}.
+|conf|a comma separated list of the configurations to use to generate the report|No. Defaults to the configurations resolved by the last resolve call
+|haltonfailure|true to halt the build on ivy failure, false to continue|No. Defaults to true
+|settingsRef|A reference to the ivy settings that must be used by this task *(since 2.0)*|No, 'ivy.instance' is taken by default.
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivy:artifactreport tofile="${basedir}/path/to/myreport.xml" />
+
+----
+
+Generates the artifact report for all configurations resolved during the last resolve call (in the same build).
+
+
+[source]
+----
+
+<ivy:artifactreport tofile="${basedir}/path/to/myreport.xml" conf="default"/>
+
+----
+
+Generates the artifact report for only the default configuration resolved during the last resolve call.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/buildlist.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/buildlist.adoc b/asciidoc/use/buildlist.adoc
new file mode 100644
index 0000000..fa1cb38
--- /dev/null
+++ b/asciidoc/use/buildlist.adoc
@@ -0,0 +1,143 @@
+
+The buildlist task enable to obtain a filelist of files (usually build.xml files) ordered according to ivy dependency information from the least dependent to the most one, or the inverse. (*__since 1.2__*)
+
+This is particularly useful combined with subant, to build a set of interelated projects being sure that a dependency will be built before any module depending on it.
+
+When the ivy.xml of the modules that you want to order doesn't contains a link:../ivyfile/info.html[revision] numbers, the rev attributes declared in the dependency is not used.
+When the ivy.xml of the modules that you want to order contains a link:../ivyfile/info.html[revision] numbers, the revision numbers are used.    If the revision number doesn't match a dependency description a warning is logged and the modules is considered as different modules.  
+
+*__since 1.3__* A root attribute can also be used to include, among all the modules found, only the one that are dependencies (either direct or transitive) of a root module. This can also be used with the excluderoot attribute, which when set to true will exclude the root itself from the list.
+
+*__since 1.4.1__* A leaf attribute can also be used to include, among all the modules found, only the one that have dependencies (either direct or transitive) on a leaf module. This can also be used with the excludeleaf attribute, which when set to true will exclude the leaf itself from the list.
+
+*__since 1.4__* The ivy.sorted.modules property is set in the ant at the end of the task with a comma separated list of ordered modules. This can be useful for debug or information purpose.
+
+*__since 2.0__* The root and leaf attributes can be a delimited list of modules to use as roots.  These modules, and all their dependencies will be included in the build list.
+
+*__since 2.0__* By default, all the modules included in a circular dependency are grouped together so that any dependency of any module in the loop will apear before the modules in the loop.  This garantee that if there is a depedendency path between a module A and a module B (but no dependency path from B to A), B will alway apear before A even if A is included in a loop in the provided set of modules to sort.
+Note that circular dependency can also trigger a failure depending on the value configured in the circularDependencyStrategy of your link:../settings/conf.html#circularDependencyStrategy[settings]
+
+*__since 2.0__* When you are specifying root or leaf modules you can limit the resulting list to only direct dependencies of the roots modules or to modules that directly depends on your leaf modules.
+
+*__since 2.0__* You can also specify a restartFrom modules.  The difference with root or leaf,  is that you get a list starting at the restartFrom module followed by all the modules that would be after if the parameter would not be there (even if there is no dependency between the restartFrom and the following module).
+
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|reference|the reference of the path to set|Yes
+|ivyfilepath|the relative path from files to order to corresponding ivy files|No. Defaults to ${ivy.buildlist.ivyfilepath}
+|root|*__since 2.0__* the names of the modules which should be considered as the root of the buildlist. 
+*__since 1.3__* Was limited to only one module name before 2.0.|No. Defaults to no root (all modules are used in the build list)
+|excluderoot|*__since 1.3__* true if the root defined should be excluded from the list|No. Defaults to false
+|leaf|*__since 2.0__* the names of the modules which should be considered as the leaf of the buildlist. 
+*__since 1.4.1__* Was limited to only one module name before 2.0.|No. Defaults to no leaf (all modules are used in the build list)
+|onlydirectdep|*__since 2.0__* true if the
+resulting list should be restricted to direct dependencies of root modules or modules that directly depends on the leaf modules.
+
+This field is ignored when neither root neither leaf is filled.
+     |No. Defaults to no false
+|delimiter|*__since 2.0__* delimiter to use when specifying multiple module names in the root and leaf properties.|No. Defaults to the comma (,) character.
+|excludeleaf|*__since 1.4.1__* true if the leaf defined should be excluded from the list|No. Defaults to false
+|haltonerror|true to halt the build when an invalid ivy file is encountered, false to continue|No. Defaults to true
+|skipbuildwithoutivy|Deprecated, use onMissingDescriptor instead. true to skip files of the fileset with no corresponding ivy file, false otherwise. If false the file with no corresponding ivy file will be considered as independent of the other and put at the beginning of the built filelist.|No. Defaults to false
+|onMissingDescriptor|*__since 2.0__* Specify the action to take when no module descriptor file is found for a file of the fileset. Possible values are:
+    
+    
+* head +
+put at the head of the built filelist.
+    
+* tail +
+put at the tail of the built filelist.
+    
+* skip +
+skip the file, which won't be put in the build filelist at all.
+    
+* warn +
+warn and put at the head of the build filelist.
+    
+* fail +
+halt the build with a failure.
+    
+    |No. Defaults to 'head'
+|reverse|true to obtain the list in the reverse order, i.e. from the most dependent to the least one|No. Defaults to default false
+|restartFrom|*__since 2.0__* The name of the module which should be considered as the starting point in the buildlist. This allows for the build to be started at any point in the dependency chain. 
+|No. Defaults to '*' meaning no restart point (all modules are used in the build list).
+|settingsRef|*__since 2.0__* A reference to the ivy settings that must be used by this task|No, 'ivy.instance' is taken by default.
+|=======
+
+
+
+=== Parameters specified as nested elements
+
+
+==== fileset
+
+FileSets are used to select sets of files to order.
+
+== Examples
+
+
+[source]
+----
+
+    <ivy:buildlist reference="build-path">
+      <fileset dir="projects" includes="**/build.xml"/>
+    </ivy:buildlist>
+
+----
+
+Builds a list of build.xml files sorted according to the ivy.xml files found at the same level (the default value for ivyfilepath is ivy.xml).
+
+This list can then be used like that:
+
+[source]
+----
+
+    <subant target="build" buildpathref="build-path" />
+
+----
+
+
+'''
+
+
+[source]
+----
+
+    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" reverse="true">
+      <fileset dir="projects" includes="**/build.xml"/>
+    </ivy:buildlist>
+
+----
+
+Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. The list is sorted from the most dependent to the least one.
+
+'''
+
+
+[source]
+----
+
+    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" root="myapp">
+      <fileset dir="projects" includes="**/build.xml"/>
+    </ivy:buildlist>
+
+----
+
+Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. Only build.xml files of modules which are dependencies of myapp (either direct or transitive) are put in the result list.
+
+'''
+
+
+[source]
+----
+
+    <ivy:buildlist reference="build-path" ivyfilepath="ivy/ivy.xml" leaf="mymodule">
+      <fileset dir="projects" includes="**/build.xml"/>
+    </ivy:buildlist>
+
+----
+
+Builds a list of build.xml files sorted according to the ivy.xml files found in an ivy directory relative to those build files. Only build.xml files of modules which have dependencies (direct or transitive) on mymodule are put in the result list.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/buildnumber.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/buildnumber.adoc b/asciidoc/use/buildnumber.adoc
new file mode 100644
index 0000000..d8fee6d
--- /dev/null
+++ b/asciidoc/use/buildnumber.adoc
@@ -0,0 +1,137 @@
+
+*__since 1.4__*
+The buildnumber task is similar to the ant buildnumber task, except that it uses ivy repository to find what is the latest version and calculate a new one for you.
+
+When called it sets four properties according to what has been found.
+These properties are:
+
+
+* ivy.revision +
+ the last revision found in the repository
+
+* ivy.new.revision +
+ the new revision calculated from the last one (see below)
+
+* ivy.build.number +
+ the build number found in the repository
+
+* ivy.new.build.number +
+ the new build number calculated from the last one, usually with +1
+
+
+build numbers are always numbers (composed of digit characters only).
+ivy.revision can be not set if no revision was found
+ivy.build.number can be not set if no revision was found or if no number was found in it
+ivy.new.build.number can be not set if the default new revision to use when no revision is found do not contain any number
+
+The new revision is calculated using a somewhat complex to explain but very easy to use algorithm, depending on which latest version you asked.
+
+Indeed you can ask for a new revision based upon the latest found for a particular prefix (the revision asked), then the new revision will be the one immediately after with only the prefix in common. If no prefix is set the very latest version is searched.
+
+Examples (suppose the latest version of the module is 1.3.1):
+
+[]
+|=======
+
+|1.3|1.3.1|1.3.2|1|2
+|1|1.3.1|1.4|3|4
+|2|not set|2.0|not set|0
+||1.3.1|1.3.2|1|2
+|=======
+
+Note that when asking for revision 1, you can get a revision 10.0. To avoid that you can use 1. as revision asked, but in this case ivy won't find revision 1 if its the latest one, and it will thus give 1.0 as new revision. The solution to this problem is to use versions with always the same number of parts (for instance 1.0.0 instead of 1).
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|organisation|the organisation of the module for which a new build number should be calculated|Yes
+|module|the name of the module for which a new build number should be calculated|Yes
+|branch|the branch of the module for which a new build number should be calculated|No, defaults to the default branch for this module
+|revision|the revision prefix for which a new build number should be calculated|No, defaults to no prefix (will find the latest version)
+|default|the default revision to assume when no revision prefix is asked and no revision is found|No, defaults to 0
+|defaultBuildNumber|the default build number to use for the first revision|No, defaults to 0
+|revSep|the revision separator to use when no matching revision is found, to separate the revision prefix from the build number|No, defaults to '.'
+|prefix|the prefix to use for the property names set (will be __prefix__.revision, __prefix__.new.revision, ...)|No, defaults to ivy
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*.|No, 'ivy.instance' is taken by default.
+|resolver|the name of the resolver to use for build number calculation *__(since 2.1)__*|No, all available resolvers will be used by default.
+|=======
+
+
+== Examples
+
+Here is how it can be used (suppose 1.3.1 is the latest version of ivy in the repository):
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" />
+
+----
+
+will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number
+
+
+'''
+
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" revision="1.3" />
+
+----
+
+will set 1.3.1 as revision, 1.3.2 as new revision, 1 as build number and 2 as new build number
+
+
+'''
+
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" revision="1.2" />
+
+----
+
+will set 1.2 as revision, 1.2.1 as new revision, no build number and 1 as new build number
+
+
+'''
+
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" revision="1." />
+
+----
+
+will set 1.3.1 as revision, 1.4 as new revision, 3 as build number and 4 as new build number
+
+
+'''
+
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" revision="3." />
+
+----
+
+will set no revision, 3.0 as new revision, no build number and 0 as new build number
+
+
+'''
+
+
+[source]
+----
+
+<ivy:buildnumber organisation="apache" module="ivy" revision="1.4-RC" defaultBuildNumber="1" revSep=""/>
+
+----
+
+If called while no release candidate is in the repository, will set ivy.revision to 1.4-RC1. Then it will increment each time, 1.4-RC2, 1.4-RC3, and so on.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/buildobr.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/buildobr.adoc b/asciidoc/use/buildobr.adoc
new file mode 100644
index 0000000..32d7798
--- /dev/null
+++ b/asciidoc/use/buildobr.adoc
@@ -0,0 +1,93 @@
+
+*__since 2.3__* From a set of jar artifacts, this task generates an OBR (OSGi Bundle Repository) descriptor. It could be then used by the link:../resolver/obr.html[obr resolver].
+
+The set of jars which will be described by the OBR can be defined in 4 exclusive ways:
+
+
+* via an Ivy resolver: every jar listed by the resolver will be taken into account +
+
+* by defining a root directory: every jar found recursively in that folder will be taken into account +
+
+* via the name of an Ivy cache: every artifact contained in the cache will be taken into account +
+
+* *__since 2.4__* via a resolve: this task is a link:../use/postresolvetask.html[post resolve task] (with all the behaviour and attributes common to all post resolve tasks), thus ever artifact which has been resolved will be taken into account; it is especially useful for building a link:../osgi/target-platform.html[target platform] +
+
+
+NB: among every listed files or artifacts, only the actually OSGi bundles will be described by the OBR descriptor; the other files are ignored. 
+
+
+== Attributes
+
+
+*__since 2.4__* This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|out|the location of the descriptor file to generate|Yes
+|resolverName|the name of the resolver from which the jars should be to gathered|No
+|cacheName|the name of the cache from which the jars should be to gathered|No
+|baseDir|the folder into which the jars should be gather recursively|No
+|sourceType|if used as a post resolve task, 'sourceType' define the type of artifacts which should be considered as source artifacts (defaults to 'source,sources,src')|No
+|encoding|The encoding of the resulting xml file|No. Defaults to `UTF-8`
+|indent|Specify if the xml result file should be indented|No. Defaults to `true`
+|quiet|Log as debug rather than warning the rejected jars as they are illformed|No. Defaults to `false`
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+    <ivy:buildobr baseDir="${eclipse.home}" out="${basedir}/target/repo-eclipse.xml" indent="true" />
+
+----
+
+Builds an indented OBR descriptor from an Eclipse install, with their path relative to the Eclipse install.
+
+
+'''
+
+
+[source]
+----
+
+    <ivy:configure file="ivysettings.xml" />
+    <ivy:buildobr resolverName="my-file-resolver" out="${basedir}/target/repo-eclipse.xml" />
+
+----
+
+Configure an Ivy settings and builds an OBR descriptor from jars resolved by the defined resolver.
+
+
+'''
+
+
+[source]
+----
+
+    <ivy:configure file="ivysettings.xml" />
+    <ivy:buildobr cacheName="my-cache" out="${basedir}/target/repo-eclipse.xml" />
+
+----
+
+Configure an Ivy settings and builds an OBR descriptor from jars contained in the defined cache.
+
+
+'''
+
+
+[source]
+----
+
+    <ivy:configure file="ivysettings.xml" />
+    <ivy:resolve file="ivy.xml" />
+    <ivy:buildobr out="${basedir}/target-platform-obr.xml" />
+
+----
+
+Launch a resolve and then build an obr.xml describing the resolved artifacts.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/cachefileset.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/cachefileset.adoc b/asciidoc/use/cachefileset.adoc
new file mode 100644
index 0000000..3f83669
--- /dev/null
+++ b/asciidoc/use/cachefileset.adoc
@@ -0,0 +1,37 @@
+
+Constructs an ant fileset consisting of artifacts in ivy cache for a configuration (*__since 1.2__*).
+
+
+This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks. Note that this task
+does not rely on retrieve, because built fileset is made of artifacts direcly in ivy cache.
+
+
+Please prefer the use of retrieve + standard ant path creation, which make your build
+more independent from ivy (once artifacts are properly retrieved, ivy is not required any more).
+
+
+Built fileset is registered in ant with a given id, and can thus be used like any other ant fileset using
+refid.
+
+
+=== Limitation
+
+A fileset, in Ant, requires a base directory from within which the files are included/excluded. The cachefileset task, in Ivy, internally tries to determine a common base directory across all the resolved artifacts' files that have been downloaded in the Ivy repository cache(s). Given that Ivy can be configured to consist multiple repository caches and each one can potentially be on a different filesystem root, there are times, when cachefileset cannot determine a common base directory for these resolved artifacts. The cachefileset throws an exception in such cases.
+
+
+=== Alternative task
+
+If cachefileset doesn't fit the need of your use case (maybe due to the limitations noted above), the link:../use/resources.html[resources] task could be an alternative task to use in certain cases.
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|setid|the id to reference the built fileset|Yes
+|conf|a comma separated list of the configurations to put in the created path|No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
+|type|comma separated list of artifact types to accept in the path, * for all|No. Defaults to *
+|settingsRef|*__(since 2.0)__* A reference to the ivy settings that must be used by this task|No, 'ivy.instance' is taken by default.
+|=======
+
+
+	
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/cachepath.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/cachepath.adoc b/asciidoc/use/cachepath.adoc
new file mode 100644
index 0000000..4a84b82
--- /dev/null
+++ b/asciidoc/use/cachepath.adoc
@@ -0,0 +1,61 @@
+
+Constructs an ant path consisting of artifacts in ivy cache (or origin location with depending on useOrigin setting) for a resolved module configuration.
+
+This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+If you want to make your build more independent from Ivy, you could consider using the link:../use/retrieve.html[retrieve task]. Once the artifacts are properly retrieved, you can use standard Ant path creation which makes Ivy not necessary any more.
+
+Built path is registered in ant with a given id, and can thus be used like any other ant path using refid.
+  
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|pathid|the id to reference the built path|Yes
+|conf|a comma separated list of the configurations to put in the created path|No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
+|type|comma separated list of artifact types to accept in the path, * for all (*__since 1.2__*)|No. Defaults to *
+|settingsRef|*__(since 2.0)__* A reference to the ivy settings that must be used by this task|No, 'ivy.instance' is taken by default.
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+<cachepath pathid="default.classpath" conf="default" />
+
+----
+
+Construct an ant path composed of all artifacts being part of the default configuration obtained through the last resolve call.
+
+
+'''
+
+
+
+[source]
+----
+
+<cachepath pathid="default.classpath" conf="default" useOrigin="true" />
+
+----
+
+Same as before but will use the original location for local artifacts, and the cache location for other artifacts.
+
+
+'''
+
+
+
+[source]
+----
+
+<ivy:cachepath organisation="emma" module="emma" revision="2.0.4217" inline="true" conf="ant" pathid="emma.classpath"/>
+<taskdef resource="emma_ant.properties" classpathref="emma.classpath" /> 
+
+----
+
+Resolves the emma module in version 2.0.4217, constructs an ant path with the corresponding artifacts, and then define the emma tasks using this path.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/checkdepsupdate.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/checkdepsupdate.adoc b/asciidoc/use/checkdepsupdate.adoc
new file mode 100644
index 0000000..1b7b6bc
--- /dev/null
+++ b/asciidoc/use/checkdepsupdate.adoc
@@ -0,0 +1,69 @@
+
+Display dependency updates on the console. This task can also show transitive dependencies updates and detect missing or new dependencies if you update dependencies.
+
+This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+Please prefer the use of retrieve + standard ant path creation, which make your build more independent from ivy (once artifacts are properly retrieved, ivy is not required any more).
+
+
+== Attributes
+
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|revisionToCheck|target revision to check|No. Defaults to 'latest.integration'
+|download|specify if artifact should be downloaded when new updates are found|No. Defaults to 'false'
+|checkIfChanged|When set to true, the resolve will compare the result with the last resolution done on this module, with those configurations in order to define the property ivy.deps.changed.  Put it to false may provides slightly better performance.|No, default to 'false'
+|showTransitive|set to true if you want to see potential updates on transitive dependencies|No. Defaults to 'false'
+|=======
+
+
+
+== Example
+
+Suppose we have two dependencies one called __mydep__ in revision 1.0 and one called __myotherdependency__ in revision 2.0.
+__mydep__ has a transitive dependency on __mytransitivedependency__ in revision 2.2.
+
+Then:
+
+[source]
+----
+
+<checkdepsupdate />
+
+----
+
+will display the following updates in the console:
+
+[source]
+----
+
+Dependencies updates available :
+   mycompany#mydep    1.0 -> 2.0
+   mycompany#myotherdependency  2.0 -> 2.2
+
+----
+
+Same example with transitive dependencies :
+
+[source]
+----
+
+<checkdepsupdate showTransitive="true" />
+
+----
+
+will display the following updates in the console:
+
+[source]
+----
+
+Dependencies updates available :
+   mycompany#mydep    1.0 -> 2.0
+   mycompany#myotherdependency  2.0 -> 2.2
+   mycompany##mytransitivedependency (transitive)    2.2 -> 2.4
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/cleancache.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/cleancache.adoc b/asciidoc/use/cleancache.adoc
new file mode 100644
index 0000000..8118572
--- /dev/null
+++ b/asciidoc/use/cleancache.adoc
@@ -0,0 +1,49 @@
+
+*__since 2.0__*
+Cleans the Ivy cache.
+
+This task is roughly equivalent to:
+
+[source]
+----
+
+<delete dir="${ivy.cache.dir}" />
+
+----
+
+Using the regular Ant delete task is more flexible, since it allows to specify the files to delete. But it requires an Ivy settings to be loaded, and settings scoping is possible only by using suffixed ant property for the cache directory. 
+
+This task loads the Ivy settings as any other post settings task, and allows easy scoping with the attribute settingsRef.
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|settingsRef|A reference to the ivy settings that must be used by this task|No, 'ivy.instance' is taken by default.
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivy:cleancache />
+
+----
+
+Cleans the cache directory as defined in the loaded settings (by default ~/.ivy2/cache)
+
+
+[source]
+----
+
+<ivy:cleancache settingsRef="mysettings"/>
+
+----
+
+Cleans the cache directory as defined in the loaded settings identified as 'mysettings'
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/configure.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/configure.adoc b/asciidoc/use/configure.adoc
new file mode 100644
index 0000000..772ca1a
--- /dev/null
+++ b/asciidoc/use/configure.adoc
@@ -0,0 +1,90 @@
+
+The configure task is used to configure ivy with an xml settings file.
+
+
+See link:../settings.html[Settings Files] for details about the settings file itself.
+
+
+
+*__since 2.0__* The file loaded used to be called configuration file in versions prior to 2.0. The name 'settings' and the use of the ivy.settings.file is new to 2.0.
+
+*__since 2.0__* It is also possible to configure Ivy with the link:../use/settings.html[settings] declaration. The difference with this task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|settingsId|The settings id useable in the settingsRef attributes of the ivy task that needs a setting.  Note that the ivy tasks will search by default for the settings with the id "ivy.instance", which is the default value.|No, defaults to "ivy.instance"
+|file|path to the settings file to use|No. If a file is provided, url is ignored. If none are provided, then it attempts to find a file at ${ivy.settings.file}, and if this file does not exist, it uses ${ivy.settings.url} *__(since 2.3)__* or a link:../samples/ivysettings-default.xml[default settings file]
+|url|url of the settings file to use
+|override|Specify what to do when another settings with the same id has already been loaded.
+* true +
+ the current settings will take precedence over any previously defined setting with this id
+* false +
+ the current settings will not override a previously defined setting with this id
+* notallowed +
+an error is raised if a settings has already been defined with this id|No, defaults to "notallowed"
+|host|http authentication host|No, unless authentication is required
+|realm|http authentication realm
+|username|http authentication user name
+|passwd|http authentication password
+|=======
+
+
+=== HTTP Authentication
+
+If any of the url you use in ivy (especially in dependency resolvers) need http
+authentication, then you have to provide the host, realm, username and passwd
+attributes of the configure task. These settings will then be used in any
+further call to ivy tasks.
+
+
+
+*Since 1.4:*
+It's also possible to configure authentication settings for multiple urls. This can be done with the <credentials> subelements. See the examples for more details.
+
+
+=== Examples
+
+
+==== Simplest settings
+
+
+[source]
+----
+<ivy:configure />
+----
+
+Use either ${ivy.settings.file} if it exists, or the link:../samples/ivysettings-default.xml[default settings file]
+
+==== Configure with a file
+
+
+[source]
+----
+<ivy:configure file="myconffile.xml" />
+----
+
+
+==== Configure with an url
+
+
+[source]
+----
+<ivy:configure url="http://mysite.com/myconffile.xml" />
+----
+
+
+==== Configure multiple URLs which require autentication
+
+
+[source]
+----
+
+<ivy:configure file="path/to/my/ivysettings.xml">
+  <credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd" />
+  <credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd" />
+</ivy:configure> 
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/convertmanifest.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/convertmanifest.adoc b/asciidoc/use/convertmanifest.adoc
new file mode 100644
index 0000000..d216653
--- /dev/null
+++ b/asciidoc/use/convertmanifest.adoc
@@ -0,0 +1,24 @@
+
+*__since 2.3__* Convert a MANIFEST.MF into an ivy.ml file
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|manifest|the location of the MANIFEST.MF to convert|Yes
+|ivyFile|the location of the ivy.xml file to generate|Yes
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+    <ivy:convertmanifest manifest="META-INF/MANIFEST.MF" ivyFile="ivy.xml" />
+
+----
+
+Just converts a manifest into an ivy.xml file.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/convertpom.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/convertpom.adoc b/asciidoc/use/convertpom.adoc
new file mode 100644
index 0000000..eef69d1
--- /dev/null
+++ b/asciidoc/use/convertpom.adoc
@@ -0,0 +1,24 @@
+
+*__since 2.1__* Convert pom.xml into an ivy.xml
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|pomFile|the location of the pom.xml to convert|Yes
+|ivyFile|the location of the ivy.xml to generate|Yes
+|=======
+
+
+
+== Examples
+
+
+[source]
+----
+
+    <ivy:convertpom pomFile="pom.xml" ivyFile="ivy.xml" />
+
+----
+
+Just convert an pom.xml file into an ivy.xml.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/deliver.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/deliver.adoc b/asciidoc/use/deliver.adoc
new file mode 100644
index 0000000..eb50b55
--- /dev/null
+++ b/asciidoc/use/deliver.adoc
@@ -0,0 +1,112 @@
+
+Deliver a resolved descriptor of the current module, and possibly perform a recursive delivery of dependencies.
+
+This task does two main things:
+
+=== Generate a resolved ivy file
+
+This task generates a resolved descriptor of the current module, based upon the last resolve done. The resolved ivy file contains updated information about the delivered module, such as revision and status.
+
+Moreover, all included configurations' files are included in the ivy file, and variables are replaced by their values.
+
+Finally, in the resolved ivy file, dynamic revisions are replaced by the static ones that have been found during the resolve step, so the ivy file can be used later safely to obtain the same dependencies (providing that a revision uniquely identifies a module, which should be the case for proper ivy use).
+
+*__since 1.3__* The replacement of dynamic revisions by static ones can be turned off, so that dynamic revisions are kept in the ivy file. This is an exception to the recommended standard that published module descriptors be fully resolved, so use it with caution.
+
+
+=== do recursive delivery
+
+This is done only if a deliver target is given to the deliver task.
+
+If a deliver target is set, then it is called (via an antcall) for each dependency which has not a suffisant status compared to the deliver status set for this task. This means that if you deliver an integration revision, no recursive delivery will be done.
+
+If you deliver a milestone or a release revision, deliver target will be called with each integration dependency. 
+
+The deliver target is called with the following properties available:
+
+  
+* dependency.name +
+the name of the dependency to recursively deliver
+  
+* dependency.published.status +
+the status to which the dependency should be delivered
+  
+* dependency.published.version +
+the revision to which the dependency should be delivered
+  
+* dependency.version +
+the revision of the dependency that should be delivered (the one that was retrieved during last resolve)
+
+Both 
+[source]
+----
+dependency.published.status
+----
+
+and 
+[source]
+----
+dependency.published.version
+----
+
+can be either asked to the user through ant input tasks (default behaviour), or be always the same for the whole recursive delivery process if the following properties are set:
+
+
+* recursive.delivery.status +
+set to the status to which all dependencies requiring to be delivered will be
+
+* recursive.delivery.version +
+set to the version to which all dependencies requiring to be delivered will be
+
+
+Usually the deliver target itself triggers an another ant build (using ant task) even if this is up to you to decide.
+
+The delivered ivy file will update its dependency revisions with those given here.  
+
+
+=== deliver and publish
+
+The deliver task is most of the time not called explicitly, but rather called automatically by the link:../use/publish.html[publish] task. So, when shall the deliver task be called explictly? When you actually need to separate what is performed by the deliver task (see above), from what is performed by the publish task, i.e. upload a module to a repository.
+
+And this can be particularly useful if you want to process the generated ivy file before uploading it (if you want to add automatically more information like an SCM tag used, the user who performed the release, ...).
+
+It can also be useful if you want to trigger a recursive delivery and then ensure that you get the recursively delivered modules as dependencies. In this case your build order may look like this:
+- ivy:configure
+- ivy:resolve
+- ivy:deliver with recursive delivery
+- ivy:resolve again with the ivy file generated by the recursive delivery
+- do your build stuff (compile, jar, whatever)
+- ivy:publish 
+  
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|deliverpattern|the pattern to use for ivy file delivery|No. Defaults to ${ivy.deliver.ivy.pattern}
+|pubrevision|the revision to use for the publication|No. Defaults to ${ivy.deliver.revision} if set, or the revision resolved if set, or a timestamp
+|pubbranch|the branch to use for the publication|No. Defaults to ${ivy.deliver.branch} if set, or the branch resolved if set, or nothing (branch info won't be updated)
+|pubdate|the publication date to use for the publication. This date should be either 'now', or a date given with the following pattern: yyyyMMddHHmmss|No. Defaults to 'now'
+|status|the status to use for the publication|No. Defaults to ${ivy.status}
+|delivertarget|the target to call for recursive delivery|No. No recursive delivery is done by default
+|validate|true to force ivy files validation against ivy.xsd, false to force no validation|No. Defaults to default ivy value (as configured in configuration file)
+|replacedynamicrev|true to replace dynamic revisions by static ones in the delivered file, false to avoid this replacement *__(since 1.3)__*|No. Defaults to true
+|replaceForcedRev|true to replace revisions (static or dynamic) by the revision of the resolver in link:../settings/resolvers.html#common[forced mode], false to avoid this replacement *__(since 2.2)__*|No. Defaults to false
+|merge|if a descriptor link:../ivyfile/extends.html[extends] a parent, merge the inherited information directly into the delivered descriptor.  The __extends__ element itself will be commented out in the delivered descriptor. *__(since 2.2)__*|No. Defaults to true.
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*|No, 'ivy.instance' is taken by default.
+|conf|comma-separated list of configurations to include in the delivered file. Accepts wildcards. *__(since 2.0)__*|No. Defaults to all configurations
+|generateRevConstraint|true to automatically generate a 'revConstraint' attribute in the deliverd file (see the link:../ivyfile/dependency.html[dependency] page for more info about this attribute), false to never generate this attribute *__(since 2.1.0)__*|No. Defaults to true
+|=======
+
+
+
+== Example
+
+Deliver an ivy file without the private configurations:
+
+[source]
+----
+
+<deliver conf="*(public)" /> 
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/dependencytree.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/dependencytree.adoc b/asciidoc/use/dependencytree.adoc
new file mode 100644
index 0000000..b6aa874
--- /dev/null
+++ b/asciidoc/use/dependencytree.adoc
@@ -0,0 +1,51 @@
+
+Display a dependency tree on the console.
+
+This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+Please prefer the use of retrieve + standard ant path creation, which make your build more independent from ivy (once artifacts are properly retrieved, ivy is not required any more).
+
+
+== Attributes
+
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|showEvicted|specify if evicted modules should be printed|No. Defaults to false
+|conf|a comma separated list of the configurations to take in consideration in the  dependency tree|No. Defaults to the configurations resolved by the last resolve call, or * if no resolve was explicitly called
+|haltonfailure|true to halt the build on ivy failure, false to continue|No. Defaults to true
+|validate|true to force ivy files validation against ivy.xsd, false to force no validation|No. Defaults to default ivy value (as configured in configuration file)
+|settingsRef|A reference to the ivy settings that must be used by this task *(since 2.0)*|No, 'ivy.instance' is taken by default.
+|overwrite|Overwrite the value of the property if it already exist *(since 2.0)*.  Before 2.0, the properties were always overwritten.|No, 'false' by default.
+|=======
+
+
+
+== Example
+
+Suppose we have two dependencies one called __mydep__ in revision 2.0 and one called __myotherdependency__ in revision 2.2.
+__mydep__ has a transitive dependency on __mytransitivedependency__ in revision 2.2.
+
+Then:
+
+[source]
+----
+
+<dependencytree />
+
+----
+
+will display the following tree in the console:
+
+[source]
+----
+
+Dependency tree for foobar
++- org#mydep;2.0
+   \- org#mytransitivedependency;2.2
+\- org#myotherdependency;2.2");
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/findrevision.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/findrevision.adoc b/asciidoc/use/findrevision.adoc
new file mode 100644
index 0000000..92bedf2
--- /dev/null
+++ b/asciidoc/use/findrevision.adoc
@@ -0,0 +1,48 @@
+
+*__since 1.4__*
+Finds the latest revision of a module matching a given version constraint.
+
+A version constraint is what is used when declaring a link:../ivyfile/dependency.html[dependency] on a module.
+If the module is not found the property is not set.
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|organisation|the organisation of the module to find|Yes
+|module|the the name of the module to find|Yes
+|branch|the branch of the module to find|No, defaults to the default branch for the given module
+|revision|the revision constraint to apply|Yes
+|property|the property to set with the found revision|No, defaults to ivy.revision
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*|No, 'ivy.instance' is taken by default.
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivy:findrevision organisation="apache" module="ivy" revision="latest.integration"/>
+
+----
+
+finds the latest version of ivy available in the repository and sets the property ivy.revision according to what was found.
+
+
+'''
+
+
+
+[source]
+----
+
+<ivy:findrevision organisation="apache" module="ivy" revision="1.0+"/>
+
+----
+
+same as above but only with 1.0 sub versions.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/fixdeps.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/fixdeps.adoc b/asciidoc/use/fixdeps.adoc
new file mode 100644
index 0000000..53a10ad
--- /dev/null
+++ b/asciidoc/use/fixdeps.adoc
@@ -0,0 +1,80 @@
+
+*__since 2.4__*
+The `fixdeps` task serializes transitively resolved dependencies into an ivy.xml file. 
+
+The dependencies declared in an ivy.xml can be specified as range of revisions. And the transitive dependencies too. As new versions of modules can be added to the repository anytime, resolved versions of ranges can change over time. It is then safer to resolve a range once and stick with the resolved revision. This way a resolve process is highly reproductible.
+
+It is especially useful in a very dynamic environment like the link:../osgi.html[OSGi] one.
+
+In a multi project environment some dependencies still need to be maintained loose: the one between the projects. These dependencies, as soon as they are declared in the original ivy.xml, can be kept from being fixed. In order to do so, use the inner element `keep`.
+
+The recommended setup is then to:
+
+
+* have an `ivy-spec.xml` in your project which specifies the dependencies, with ranges if needed +
+
+* have an Ant target which resolve the `ivy-spec.xml` and call `fixdeps` to generate an `ivy.xml`. This target should then only be called after `ivy-spec.xml` is modified. The generated `ivy.xml` can safely be shared in a version control repository (svn, git,...). +
+
+* make the entire build workflow based on the resolve of the generated `ivy.xml` +
+
+
+This is a link:../use/postresolvetask.html[post resolve task], with all the behaviour and attributes common to all post resolve tasks.
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|tofile|The location of the ivy file to generate|Yes
+|=======
+
+
+
+== Child elements
+
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Element|Description|Cardinality
+|keep|declares a dependency to keep from being fixed, and keep its original declaration from the original ivy.xml
+    
+These elements takes two attributes: 
+* org +
+ the organization
+* module +
+the name of the module|0..n
+|=======
+
+
+
+== Examples
+
+
+
+[source]
+----
+
+<ivy:fixdeps tofile="ivy-fixed.xml" />
+
+----
+
+Simple fix of some dependencies.
+
+
+'''
+
+
+
+[source]
+----
+
+<ivy:fixdeps tofile="ivy-fixed.xml">
+    <keep org="com.acme" module="mymodule" />
+</ivy:fixdeps>
+
+----
+
+Fix of the dependencies but keep the dependency on `com.acme#mymodule` as defined in the original ivy.xml.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/info.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/info.adoc b/asciidoc/use/info.adoc
new file mode 100644
index 0000000..1233575
--- /dev/null
+++ b/asciidoc/use/info.adoc
@@ -0,0 +1,172 @@
+
+*__since 1.4__*
+The info task ease the access to some essential data contained in an ivy file without performing a dependency resolution.
+
+The information is retrieved by setting ant properties:
+
+[options="header",cols="15%,50%"]
+|=======
+|Property|Description
+|ivy.organisation|The organisation of the module, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed.
+|ivy.module|The name of the module, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed.
+|ivy.branch|The branch of the module if any, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed.
+|ivy.revision|The revision of the module, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed.
+|ivy.status|The status of the module, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed.
+|ivy.publication|The publication time of the module, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed. *__(Since 2.2)__*
+|ivy.extra.__[any extra attribute]__|Corresponding extra attribute value, as found in the link:../ivyfile/info.html[info] tag of the ivy file parsed
+|ivy.configurations|A comma separated list of configurations of the module, as declared in the link:../ivyfile/configurations.html[configurations] section
+|ivy.public.configurations|A comma separated list of public configurations of the module, as declared in the link:../ivyfile/configurations.html[configurations] section
+|ivy.configuration.__[config name]__.desc|For each configuration with a description, a property is created containing this description. *__(Since 2.2)__*
+|ivy.artifact.__[index]__.name|For each published artifact, a property is created containing its name. *__(Since 2.2)__*
+|ivy.artifact.__[index]__.type|For each published artifact, a property is created containing its type. *__(Since 2.2)__*
+|ivy.artifact.__[index]__.ext|For each published artifact, a property is created containing its ext. *__(Since 2.2)__*
+|ivy.artifact.__[index]__.conf|For each published artifact, a property is created containing its conf. *__(Since 2.2)__*
+|ivy.artifact.__[index]__.extra.__[any extra attribute]__|For each extra attribute of the published artifact, a property is created containing its name. *__(Since 2.2)__*
+|=======
+
+
+
+*__since 2.0__*
+
+Since Ivy 2.0 this task has been enhanced to allow you to retrieve information about ivy modules in a repository.  Instead of specifying a local ivy file you may specify the organisation, module, revision pattern and (optionally) the branch of the ivy module in the repository you wish to retrieve the information for.
+
+The revision pattern is what is used when declaring a link:../ivyfile/dependency.html[dependency] on a module, identical to how the link:findrevision.html[findrevision] task works.  In fact this task can now be used in place of the findrevision task.
+
+If no matching module is found then no property values are set.
+
+You may now also set the property attribute to change the first part of the property names that are set by this task e.g. if you set the property attribute to 'mymodule' this task will set the ant properties __mymodule.organisation__, __mymodule.module__, __mymodule.revision__ etc.
+
+*__since 2.2__*
+
+Since Ivy 2.2 this task has been enhanced to also retrieve detailed information about the module's published artifacts, as well as the publication time.
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|file|the ivy file to parse|Yes, if you wish to parse an ivy file.
+No, if you are retrieving information about a module from an ivy repository.
+|organisation|the organisation of the module to find *__(since 2.0)__*|No, if you wish to parse an ivy file.
+Yes, if you are retrieving information about a module from an ivy repository.
+|module|the the name of the module to find *__(since 2.0)__*|No, if you wish to parse an ivy file.
+Yes, if you are retrieving information about a module from an ivy repository.
+|branch|the branch of the module to find *__(since 2.0)__*|No, defaults to the default branch for the given module if you are retrieving information about a module from an ivy repository.
+|revision|the revision constraint to apply *__(since 2.0)__*|No, if you wish to parse an ivy file.
+Yes, if you are retrieving information about a module from an ivy repository.
+|property|the name to use as the base of the property names set by this task *__(since 2.0)__*|No, will default to 'ivy' if not set.
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*|No, 'ivy.instance' is taken by default.
+|=======
+
+
+== Examples
+
+Given this ivy.xml file:
+
+[source]
+----
+
+<ivy-module version="1.0" xmlns:e="http://ant.apache.org/ivy/extra">
+	<info organisation="apache"
+	       module="info-all"
+	       branch="trunk"
+	       revision="1.0"
+	       status="release"
+	       e:myextraatt="myvalue"
+	/>
+	<configurations>
+		<conf name="default" />
+		<conf name="test" />
+		<conf name="private" visibility="private"/>
+	</configurations>
+	<publications>
+		<artifact name="thing1" type="jar" ext="jar" conf="default" e:data="main"/>
+		<artifact name="thing2" type="jar" ext="jar" conf="default" e:data="client"/>
+	</publications>
+	<dependencies>
+		<dependency org="org1" name="mod1.2" rev="2.0"/>
+	</dependencies>
+</ivy-module>
+
+----
+
+
+[source]
+----
+
+<ivy:info file="${basedir}/path/to/ivy.xml" />
+
+----
+
+Parses ${basedir}/path/to/ivy.xml and set properties as described above accordingly:
+
+[source]
+----
+
+ivy.organisation=apache
+ivy.module=info-all
+ivy.branch=trunk
+ivy.revision=1.0
+ivy.status=release
+ivy.extra.myextraatt=myvalue
+ivy.configurations=default, test, private
+ivy.public.configurations=default, test
+ivy.artifact.1.name=thing1
+ivy.artifact.1.type=jar
+ivy.artifact.1.ext=jar
+ivy.artifact.1.conf=default
+ivy.artifact.1.extra.data=main
+ivy.artifact.2.name=thing2
+ivy.artifact.2.type=jar
+ivy.artifact.2.ext=jar
+ivy.artifact.2.conf=default
+ivy.artifact.2.extra.data=client
+
+----
+
+Given the same ivy module in a repository:
+
+[source]
+----
+
+<ivy:info organisation="apache" module="info-all" revision="1.0" />
+
+----
+
+will set the exact same set of properties as above.  Using:
+
+[source]
+----
+
+<ivy:info organisation="apache" module="info-all" revision="1.0" property="infotest"/>
+
+----
+
+will set:
+
+[source]
+----
+
+infotest.organisation=apache
+infotest.module=info-all
+infotest.branch=trunk
+infotest.revision=1.0
+infotest.status=release
+infotest.extra.myextraatt=myvalue
+infotest.configurations=default, test, private
+infotest.public.configurations=default, test
+infotest.artifact.1.name=thing1
+infotest.artifact.1.type=jar
+infotest.artifact.1.ext=jar
+infotest.artifact.1.conf=default
+infotest.artifact.1.extra.data=main
+infotest.artifact.2.name=thing2
+infotest.artifact.2.type=jar
+infotest.artifact.2.ext=jar
+infotest.artifact.2.conf=default
+infotest.artifact.2.extra.data=client
+
+----
+

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/install.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/install.adoc b/asciidoc/use/install.adoc
new file mode 100644
index 0000000..e469a44
--- /dev/null
+++ b/asciidoc/use/install.adoc
@@ -0,0 +1,42 @@
+
+Installs a module and all its dependencies in a resolver. *__since 1.3__*
+
+The module to install should be available in a resolver, and will be installed in another resolver which should support publish.
+
+This is particularly useful for users who only have a private repository, and want to benefit from public repositories from time to time. In this case, when a module is missing in the private repository, a call to install let download the module from a public repository not usually used for dependency resolution, and install it and its dependencies in the private repository.
+
+For more details about this task and its usage see the link:../tutorial/build-repository.html[build repository tutorial]
+  
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|from|the name of the resolver in which the module must be found|Yes
+|to|the name of the resolver in which the module must be installed|Yes
+|organisation|the name of the organisation of the module to install|Yes
+|module|the name of the module to install|Yes
+|branch|the branch of the module to install *__since 2.0__*|No, defaults to default branch with exact matcher, '*' with any other matcher
+|revision|the revision of the module to install|Yes
+|type|the type(s) of artefact(s) to install.  You can give multiple values separated by commas|No, defaults to '*' meaning all types
+|conf|the configurations to install. Only the dependencies of the specified configurations will be installed. *__since 2.3__*|No, defaults to '*' meaning all configurations
+|validate|true to force ivy files validation against ivy.xsd, false to force no validation|No. Defaults to default ivy value (as configured in configuration file)
+|overwrite|true to override modules already present in the destination resolver, false otherwise|No, defaults to false
+|transitive|true to install the module and all its transitive dependencies, false to install only the module|No, defaults to false
+|matcher|the name of the matcher to use to find the modules to install|No, defaults to exact
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*|No, 'ivy.instance' is taken by default.
+|haltonfailure|true to fail build on unresolved dependencies *__since 2.0__*|No, defaults to true
+|installOriginalMetadata|true to install original metadata (if available). If the module has been originally resolved from a m2 repository, the original metadata is the original POM file *__since 2.4__*|No, defaults to false
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivy:install organisation="apache" module="commons-lang" revision="2.0" from="ivyrep" to="myfsresolver"/>
+
+----
+
+Installs the module commons-lang from apache in revision 2.0 in the resolver myfsresolver. The module is found in the resolver named 'ivyrep'.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/22bdffb9/asciidoc/use/listmodules.adoc
----------------------------------------------------------------------
diff --git a/asciidoc/use/listmodules.adoc b/asciidoc/use/listmodules.adoc
new file mode 100644
index 0000000..6864a04
--- /dev/null
+++ b/asciidoc/use/listmodules.adoc
@@ -0,0 +1,56 @@
+
+*__since 1.4__*
+Finds the list of modules in the repository matching some criteria and set a corresponding list of properties in ant.
+
+The criteria is set by given patterns matching the organisation, name branch and revision of the modules to find.
+
+To know if a module matches the criteria ivy will use the configured link:../concept.html#matcher[pattern matcher].
+
+
+== Attributes
+
+
+[options="header",cols="15%,50%,35%"]
+|=======
+|Attribute|Description|Required
+|organisation|the pattern matching the organisation of the modules to list|Yes
+|module|the pattern matching the name of the modules to list|Yes
+|branch|the pattern matching the branch of the modules to list|No, defaults to '*'
+|revision|the pattern matching the revision of the modules to list|Yes
+|matcher|the name of the pattern matcher to use for matching the modules fields|No. Defaults to exactOrRegexp.
+|property|the pattern of the property to set when a module is found|Yes
+|value|The pattern of the value to set when a module is found|Yes
+|settingsRef|A reference to the ivy settings that must be used by this task *__(since 2.0)__*|No, 'ivy.instance' is taken by default.
+|resolver|The name of the resolver to use for searching the modules *__(since 2.2.0)__*|No, all available resolvers will be used by default.
+|=======
+
+
+== Examples
+
+
+[source]
+----
+
+<ivy:listmodules organisation="apache" module="ivy" revision="*" property="ivy.[revision]" value="found"/>
+
+----
+
+will find all revisions of the module ivy in the org apache, and create one property for each revision found, the name of the property depending on the revision, the value being always 'found'
+
+
+'''
+
+
+
+[source]
+----
+
+<ivy:listmodules organisation="*" module="ivy*" revision="1.0" matcher="glob" property="modules.[module]" value="[organisation]"/>
+
+----
+
+use the glob matcher to find all modules which name starts with ivy with revision 1.0, and sets for each a property with module name found  and organisation for value.
+Example:
+modules.ivy=apache
+modules.ivyde=apache
+modules.ivytools=ivytools
\ No newline at end of file