Index: images/ivy-publish-fc.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = application/octet-stream

Property changes on: images\ivy-publish-fc.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Index: ivyfile.html
===================================================================
--- ivyfile.html	(revision 670429)
+++ ivyfile.html	(working copy)
@@ -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>
Index: ivyfile/configurations.html
===================================================================
--- ivyfile/configurations.html	(revision 670429)
+++ ivyfile/configurations.html	(working copy)
@@ -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.
 
Index: ivyfile/info.html
===================================================================
--- ivyfile/info.html	(revision 670429)
+++ ivyfile/info.html	(working copy)
@@ -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>.
 
Index: reference.html
===================================================================
--- reference.html	(revision 670429)
+++ reference.html	(working copy)
@@ -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>
Index: use/deliver.html
===================================================================
--- use/deliver.html	(revision 670429)
+++ use/deliver.html	(working copy)
@@ -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.
 
Index: use/publish.html
===================================================================
--- use/publish.html	(revision 670429)
+++ use/publish.html	(working copy)
@@ -25,13 +25,18 @@
 </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).
   
