Author: xavier
Date: Mon Jun 23 19:20:24 2008
New Revision: 670993
URL: http://svn.apache.org/viewvc?rev=670993&view=rev
Log:
apply documentation patch from Sakari Maaranen
Added:
ant/ivy/core/trunk/doc/images/ivy-publish-fc.odg (with props)
ant/ivy/core/trunk/doc/images/ivy-publish-fc.png (with props)
Modified:
ant/ivy/core/trunk/doc/ivyfile.html
ant/ivy/core/trunk/doc/ivyfile/configurations.html
ant/ivy/core/trunk/doc/ivyfile/info.html
ant/ivy/core/trunk/doc/reference.html
ant/ivy/core/trunk/doc/use/deliver.html
ant/ivy/core/trunk/doc/use/publish.html
Added: ant/ivy/core/trunk/doc/images/ivy-publish-fc.odg
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/images/ivy-publish-fc.odg?rev=670993&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ant/ivy/core/trunk/doc/images/ivy-publish-fc.odg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: ant/ivy/core/trunk/doc/images/ivy-publish-fc.png
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/images/ivy-publish-fc.png?rev=670993&view=auto
==============================================================================
Binary file - no diff available.
Propchange: ant/ivy/core/trunk/doc/images/ivy-publish-fc.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Modified: ant/ivy/core/trunk/doc/ivyfile.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/ivyfile.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/ivyfile.html (original)
+++ ant/ivy/core/trunk/doc/ivyfile.html Mon Jun 23 19:20:24 2008
@@ -25,7 +25,7 @@
</head>
<body>
<textarea id="xooki-source">
-Ivy use is entirely based on what is called ivy files. Ivy files are xml
files, usually called ivy.xml, containing the description of the dependencies
of a module, its published artifacts and its configurations.
+Ivy use is entirely based on <em>module descriptors</em> known as "ivy files".
Ivy files are xml files, usually called ivy.xml, containing the description of
the dependencies of a module, its published artifacts and its configurations.
Here is the simplest ivy file you can write:
<code type="xml">
@@ -36,7 +36,7 @@
</ivy-module>
</code>
-If you want to see a sample file using almost all possibilities of ivy files,
check this one, <a href="samples/ivy-sample-xslt.xml">with</a> or <a
href="samples/ivy-sample.xml">without</a> xslt.
+If you want to see a sample module descriptor using almost all possibilities
of ivy files, check this one, <a href="samples/ivy-sample-xslt.xml">with</a> or
<a href="samples/ivy-sample.xml">without</a> xslt.
Before beginning the reference itself, it is required to have in mind the
terminology defined in the <a href="reference.html">main page</a> of this
reference documentation.
@@ -53,6 +53,22 @@
</ivy-module>
</code>
+<h2>Dynamic and <a name="resolved">resolved</a> ivy files</h2>
+
+A module descriptor (ivy file) is needed both before and after the publication
of each revision of the module. Depending on the case, a module descriptor can
be either <em>dynamic</em> or <em>resolved</em>:
+
+<h3>Dynamic descriptor for module development</h3>
+
+During the module development time, between publications, the descriptor helps
in managing all the possibly changing dependencies of the module. For that
purpose, development time ivy files can declare dynamic dependencies to allow
for a greater flexibility of use. <a
href="ivyfile/dependency.html#revision">Dynamic revision</a> references like
"latest.integration" or "1.0.+" are possible and may resolve to different
artifacts at different times. Variables can be used for even more flexibility.
Development time ivy files are hence called "dynamic", because they can produce
different results over time. The dynamic ivy files are normally considered
source files and kept with them (under SCM control).
+
+<h3>Resolved descriptors for publishing</h3>
+
+At each publication, another kind of a module descriptor is needed to document
the dependencies of the particular published revision of the module. For that
purpose, the descriptor usually needs to be fixed as its dependencies should no
longer change. In doing so, the published module revision gets fixed,
explicitly resolved dependencies. No variables are allowed either. Such
publication-friendly, static ivy files are called "resolved", because they
should always produce the same results. The resolved ivy files are comparable
to published artifacts and are kept with them in a repository.
+
+Resolved ivy files are generated from their original dynamic ivy files via the
<a href="use/deliver.html">deliver</a> task.
+
+Note that although it is technically possible to publish module revisions with
dynamic ivy files, it is not a generally recommended practice.
+
<h1>Hierarchical Index</h1>
<pre>
ivy-module
@@ -83,7 +99,7 @@
<h1>ivy-module</h1>
<b>Tag:</b> ivy-module
-Root tag of any ivy-file.
+The root tag of any ivy file (module descriptor).
<h2>Attributes</h2>
<table class="ivy-attributes">
<thead>
Modified: ant/ivy/core/trunk/doc/ivyfile/configurations.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/ivyfile/configurations.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/ivyfile/configurations.html (original)
+++ ant/ivy/core/trunk/doc/ivyfile/configurations.html Mon Jun 23 19:20:24 2008
@@ -27,7 +27,7 @@
<textarea id="xooki-source">
<b>Tag:</b> configurations <b>Parent:</b> <a
href="../ivyfile.html">ivy-module</a>
-Container for configuration element. If this container is not present, it is
assumed that the module has one public configuration called 'default'.
+A container for configuration elements. If this container is not present, it
is assumed that the module has one public configuration called 'default'.
<span class="since">since 1.3</span> You can define a new default conf mapping
on this container by specifying the defaultconfmapping attribute.
Modified: ant/ivy/core/trunk/doc/ivyfile/info.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/ivyfile/info.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/ivyfile/info.html (original)
+++ ant/ivy/core/trunk/doc/ivyfile/info.html Mon Jun 23 19:20:24 2008
@@ -27,7 +27,7 @@
<textarea id="xooki-source">
<b>Tag:</b> info <b>Parent:</b> <a href="../ivyfile.html">ivy-module</a>
-Gives information about the module this ivy file describe.
+Gives identification and basic information about the module this ivy file
describes.
<span class="since">since 1.4</span> This tag supports <a
href="../concept.html#extra">extra attributes</a>.
Modified: ant/ivy/core/trunk/doc/reference.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/reference.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/reference.html (original)
+++ ant/ivy/core/trunk/doc/reference.html Mon Jun 23 19:20:24 2008
@@ -46,7 +46,7 @@
<li>[[configuration]]</li>
This part is dedicated to the specification of the settings file of Ivy
(usually called ivysettings.xml). It also gives the list of built-in dependency
resolvers available in ivy.
<li>[[ivyfile]]</li>
-This part is the reference of the specification of the ivy files, the files in
which you describe your dependencies. If you have any question of what can be
done or not in an ivy file, you will have the answer here.
+This part is the reference of the specification of the module descriptors, the
ivy files in which you describe your dependencies. If you have any question of
what can be done or not in an ivy file, you will have the answer here.
<li>[[ant]]</li>
This part describes how to use ivy from ant. It's in this section that all ant
tasks brought by ivy are specified.
<li>[[standalone]]</li>
Modified: ant/ivy/core/trunk/doc/use/deliver.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/use/deliver.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/use/deliver.html (original)
+++ ant/ivy/core/trunk/doc/use/deliver.html Mon Jun 23 19:20:24 2008
@@ -25,16 +25,18 @@
</head>
<body>
<textarea id="xooki-source">
-Delivers a resolved ivy file of the current module, and possibly do recursive
delivery of dependencies.
+Deliver a resolved descriptor of the current module, and possibly perform a
recursive delivery of dependencies.
+
This task does two main things:
<h2>Generate a resolved ivy file</h2>
-This task generates a resolved ivy file 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.
+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.
+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).
-<span class="since">since 1.3</span> The replacement of dynamic revisions by
static ones can be turned off, so that dynamic revisions are kept in the ivy
file.
+<span class="since">since 1.3</span> 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.
+
<h2>do recursive delivery</h2>
This is done only if a deliver target is given to the deliver task.
Modified: ant/ivy/core/trunk/doc/use/publish.html
URL:
http://svn.apache.org/viewvc/ant/ivy/core/trunk/doc/use/publish.html?rev=670993&r1=670992&r2=670993&view=diff
==============================================================================
--- ant/ivy/core/trunk/doc/use/publish.html (original)
+++ ant/ivy/core/trunk/doc/use/publish.html Mon Jun 23 19:20:24 2008
@@ -25,12 +25,17 @@
</head>
<body>
<textarea id="xooki-source">
-Publishes the current modules artifacts.
+Publishes the current module's <a
href="../ivyfile/publications.html">artifacts</a> and the <a
href="../ivyfile.html#resolved">resolved descriptor</a> (delivered ivy file).
-This task is meant to publish the declared published artifacts of the current
module to a repository.
+This task is meant to publish the current module descriptor together with its
declared publication artifacts to a repository.
-The repository is given through the name of a resolver declared in current ivy
configuration. See <a href="../configuration.html">configuration</a> for
details about resolver supporting artifact publishing.
-It also publishes the delivered ivy file (except if you don't want), and even
deliver it if it has not been done with a previous deliver call or if
forcedeliver is set to true. That's why this task takes some parameters useful
only for delivery.
+All the artifacts must have been created <em>before</em> calling this task. It
does not create the artifacts themselves, but expects to find them at the
location indicated by the artifacts pattern.
+
+The target repository is given through the name of a resolver declared in
current ivy settings. See <a href="../configuration.html">settings</a> for
details about resolver supporting artifact publishing.
+
+It also publishes the delivered ivy file (except if you don't want), and even
deliver it, if it has not been done with a previous deliver call or if
forcedeliver is set to true. That's why this task takes some parameters useful
only for delivery. See the illustration below:
+
+<p><img alt="publish flowchart" src="../images/ivy-publish-fc.png" width="360"
height="473"/></p>
<span class="since">since 1.4.1</span>
The source artifact pattern can be specified either as an attribute on the
task (artifactspattern) or using a list of nested artifacts element (see
examples below).
