You are viewing a plain text version of this content. The canonical link for it is here.
Posted to ivy-commits@incubator.apache.org by xa...@apache.org on 2007/01/06 17:23:40 UTC
svn commit: r493514 - in /incubator/ivy/trunk/doc: ./ doc/
doc/configuration/ doc/resolver/ doc/use/
Author: xavier
Date: Sat Jan 6 09:23:39 2007
New Revision: 493514
URL: http://svn.apache.org/viewvc?view=rev&rev=493514
Log:
take advantage of shortcuts, clean some bad links and document how to write doc.
Added:
incubator/ivy/trunk/doc/write-doc.html
Modified:
incubator/ivy/trunk/doc/config.json
incubator/ivy/trunk/doc/doc/bestpractices.html
incubator/ivy/trunk/doc/doc/configuration/outputters.html
incubator/ivy/trunk/doc/doc/resolver/filesystem.html
incubator/ivy/trunk/doc/doc/tutorial.html
incubator/ivy/trunk/doc/doc/use/cachepath.html
incubator/ivy/trunk/doc/doc/use/deliver.html
incubator/ivy/trunk/doc/doc/use/postresolvetask.html
incubator/ivy/trunk/doc/doc/use/repreport.html
incubator/ivy/trunk/doc/doc/use/retrieve.html
incubator/ivy/trunk/doc/get-involved.html
incubator/ivy/trunk/doc/toc.json
Modified: incubator/ivy/trunk/doc/config.json
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/config.json?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/config.json (original)
+++ incubator/ivy/trunk/doc/config.json Sat Jan 6 09:23:39 2007
@@ -1 +1,7 @@
-{debug:true, jira: {ids: ['IVY'], url: 'http://issues.apache.org/jira'}}
+{debug:true,
+ jira: {ids: ['IVY'], url: 'http://issues.apache.org/jira'},
+ shortcuts: {
+ svn: {pre: 'https://svn.apache.org/repos/asf/incubator/ivy/trunk/'},
+ ant: {pre: xooki.c.root+'doc/use/', post:'.html'}
+ }
+}
Modified: incubator/ivy/trunk/doc/doc/bestpractices.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/bestpractices.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/bestpractices.html (original)
+++ incubator/ivy/trunk/doc/doc/bestpractices.html Sat Jan 6 09:23:39 2007
@@ -25,13 +25,13 @@
<li>reliability</li> Ibiblio maven repository is not particularly well known for its reliability (we often experience major slow down or even complete break of the site), and ivyrep is only supported by a small company (yes we are only a small company!). So slow down and site hang occurs also. And if the repository you rely on is down, this can cause major slow down in your development or release process.
<li>accuracy</li> a public repository usually contains much more than what you actually need (except maybe ivyrep which certainly features much less than what you need :-)). Is it a problem? We think so. We think that in an enterprise environment the libraries you use should step through some kind of validation process before being used in every projects of your company. And what better way to do so? Setup an enterprise repository with only the libraries you actually want to use. This will not only ensure a better quality of your application dependencies, but help to have the same versions everywhere, and even help when declaring your module dependencies, if you use a tool like IvyDE, the code completion will only show relevant information about your repository, with only the libraries you actually want to see.
</ul>
-Note that it's not because you use an enterprise repository that you have to build it entirely by hand. Ivy features an [ivy:ant:install] task which can be used to install modules from a repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.
+Note that it's not because you use an enterprise repository that you have to build it entirely by hand. Ivy features an [[ant:install]] task which can be used to install modules from a repository to another one, so it can be used to selectively install modules from a public repository to your enterprise repository, where you will then be able to ensure control, reliability and accuracy.
<h1>Always use patterns with at least organisation and module</h1>
-Ivy is very flexible and can accomodate a lot of existing repositories, using the concept of <a href="../doc/concept#pattern.html">patterns</a>. But if your repository doesn't exist yet, we strongly recommend to always use the organisation and the module name in your pattern, even for private repository where you put only your own modules (which all the same organisation). Why? Because Ivy listing feature rely on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like [ivy:ant:install] or [ivy:ant:rereport].
+Ivy is very flexible and can accomodate a lot of existing repositories, using the concept of <a href="../doc/concept#pattern.html">patterns</a>. But if your repository doesn't exist yet, we strongly recommend to always use the organisation and the module name in your pattern, even for private repository where you put only your own modules (which all the same organisation). Why? Because Ivy listing feature rely on the token it can find in the pattern. If you have no organisation token in your pattern, Ivy won't be able to list the (only?) organisation in your repository. And this can be a problem for code completion in IvyDE, for example, but also for repository wide tasks like [[ant:install]] or [[ant:repreport]].
<h1>Public ivyconf.xml with public repositories</h1>
-If you create a public repository, provide an url to corresponding <a href="../doc/configuration.html">ivyconf.xml</a>. It's pretty easy to do, and if someone want to leverage your repository, he will just have to call [ivy:ant:configure] with the url of your ivyconf.xml, or <a href="../doc/configuration/include.html">include</a> it in its own configuration file, which makes it really easy to combine several public repositories.
+If you create a public repository, provide an url to corresponding <a href="../doc/configuration.html">ivyconf.xml</a>. It's pretty easy to do, and if someone want to leverage your repository, he will just have to call [[ant:configure]] with the url of your ivyconf.xml, or <a href="../doc/configuration/include.html">include</a> it in its own configuration file, which makes it really easy to combine several public repositories.
<h1>Dealing with integration versions</h1>
Very often especially when working in a team or with several modules, you will need to rely on intermediate, non finalized versions of your modules. These versions are what we call integration versions, because their main objective is to be integrated with other modules to make and test an application or a framework.
Modified: incubator/ivy/trunk/doc/doc/configuration/outputters.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/configuration/outputters.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/configuration/outputters.html (original)
+++ incubator/ivy/trunk/doc/doc/configuration/outputters.html Sat Jan 6 09:23:39 2007
@@ -23,7 +23,7 @@
| default | 1 | 1 | 0 | 0 || 1 | 1 |
---------------------------------------------------------------------
</code>
-<li>an xml report outputter (<a href="http://svn.jayasoft.org/projects/tools/ivy/src/java/fr/jayasoft/ivy/report/XmlReportOutputter.java">XmlReportOutputter</a>)</li>which produces an xml report in the cache, which is mandatory for correct Ivy behaviour, since it's that report which is used when you do a post resolve step in a separate buid from the resolve itself. It's also this xml report which is processed to generate all the different reports available in the [ivy:ant:report] task.
+<li>an xml report outputter (<a href="http://svn.jayasoft.org/projects/tools/ivy/src/java/fr/jayasoft/ivy/report/XmlReportOutputter.java">XmlReportOutputter</a>)</li>which produces an xml report in the cache, which is mandatory for correct Ivy behaviour, since it's that report which is used when you do a post resolve step in a separate buid from the resolve itself. It's also this xml report which is processed to generate all the different reports available in the [[ant:report]] task.
</ul>
The child tag used for the parser must be equal to a name of a report outputter type (added with the typedef tag).
Modified: incubator/ivy/trunk/doc/doc/resolver/filesystem.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/resolver/filesystem.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/resolver/filesystem.html (original)
+++ incubator/ivy/trunk/doc/doc/resolver/filesystem.html Sat Jan 6 09:23:39 2007
@@ -27,7 +27,7 @@
<tbody>
<tr><td>m2compatible</td><td>True if this resolver should be maven2 compatible, false otherwise <span class="since">since 1.3</span></td>
<td>No, defaults to false</td></tr>
- <tr><td>local</td><td>True if this resolver should be considered local, false otherwise <span class="since">since 1.4</span>. See useOrigin attribute on the [ivy:ant:resolve] task for details.</td>
+ <tr><td>local</td><td>True if this resolver should be considered local, false otherwise <span class="since">since 1.4</span>. See useOrigin attribute on the [[ant:resolve]] task for details.</td>
<td>No, defaults to true</td></tr>
</tbody>
</table>
Modified: incubator/ivy/trunk/doc/doc/tutorial.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/tutorial.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/tutorial.html (original)
+++ incubator/ivy/trunk/doc/doc/tutorial.html Sat Jan 6 09:23:39 2007
@@ -6,37 +6,37 @@
</head>
<body>
<textarea id="xooki-source">
-The best way to learn is to practice! That's what the ivy tutorials will help you to do, to discover some of the great ivy <a href="../features.html">features</a>.
-
-Here is the very first tutorial, it doesn't even require to install Ivy, and should not take more than 30 seconds if you already have ant and a jdk properly installed:
-<ul>
-<li>make sure you have <a href="http://ant.apache.org/">ant</a> 1.6.2 or greater and a <a href="http://java.sun.com">jdk</a> properly installed</li>
-<li>copy <a href="../samples/build.xml">this build file</a> in an empty directory on your local filesystem (and make sure you name it build.xml)</li>
-<li>open a console in this directory and run "ant". That's it!</li>
-</ul>
-If you have any trouble, check the <a href="../faq.html">FAQ</a>, it may be related to your internet connection (proxy anyone?).
-
-OK, you've seen how easy it is to make your first step with ivy? Go ahead with the other tutorials, but before make sure you have properly <a href="install.html">installed</a> ivy and downloaded the tutorials sources (included in all ivy distributions, in the src/example directory).
-
-The following tutorials are available:
-<ul>
-<li><a href="tutorial/start.html">Quick Start</a></li>
-guide you through your very first steps with ivy.
-<li><a href="tutorial/ivyrep.html">Using IvyRep</a></li>
-show you the out of the box power of ivy + ivyrep.
-<li><a href="tutorial/defaultconf.html">Configuring default resolver</a></li>
-give you a better understanding of the default configuration and show you how to customize it to your needs.
-<li><a href="tutorial/multiple.html">Multiple Resolvers</a></li>
-teach you how to configure Ivy to find its dependencies in multiple places.
-<li><a href="tutorial/dual.html">Dual Resolver</a></li>
-help you configure ivy to find ivy files in one place and artifacts in another.
-<li><a href="tutorial/multi-project.html">Project Dependencies</a></li>
-makes you touch the interest of using ivy in multi project environment.
-<li><a href="tutorial/conf.html">Using Ivy Configurations</a></li>
-show how to use configurations in ivy file to define set of artifacts.
-<li><a href="tutorial/build-repository.html">Building a repository</a></li>
-show how to build your own enterprise repository.
-</ul>
+The best way to learn is to practice! That's what the ivy tutorials will help you to do, to discover some of the great ivy <a href="../features.html">features</a>.
+
+Here is the very first tutorial, it doesn't even require to install Ivy, and should not take more than 30 seconds if you already have ant and a jdk properly installed:
+<ul>
+<li>make sure you have <a href="http://ant.apache.org/">ant</a> 1.6.2 or greater and a <a href="http://java.sun.com">jdk</a> properly installed</li>
+<li>copy <a href="../samples/build.xml">this build file</a> in an empty directory on your local filesystem (and make sure you name it build.xml)</li>
+<li>open a console in this directory and run "ant". That's it!</li>
+</ul>
+If you have any trouble, check the <a href="../faq.html">FAQ</a>, it may be related to your internet connection (proxy anyone?).
+
+OK, you've seen how easy it is to make your first step with ivy? Go ahead with the other tutorials, but before make sure you have properly <a href="install.html">installed</a> ivy and downloaded the tutorials sources (included in all ivy distributions, in the [[svn:src/example]] directory).
+
+The following tutorials are available:
+<ul>
+<li><a href="tutorial/start.html">Quick Start</a></li>
+guide you through your very first steps with ivy.
+<li><a href="tutorial/ivyrep.html">Using IvyRep</a></li>
+show you the out of the box power of ivy + ivyrep.
+<li><a href="tutorial/defaultconf.html">Configuring default resolver</a></li>
+give you a better understanding of the default configuration and show you how to customize it to your needs.
+<li><a href="tutorial/multiple.html">Multiple Resolvers</a></li>
+teach you how to configure Ivy to find its dependencies in multiple places.
+<li><a href="tutorial/dual.html">Dual Resolver</a></li>
+help you configure ivy to find ivy files in one place and artifacts in another.
+<li><a href="tutorial/multi-project.html">Project Dependencies</a></li>
+makes you touch the interest of using ivy in multi project environment.
+<li><a href="tutorial/conf.html">Using Ivy Configurations</a></li>
+show how to use configurations in ivy file to define set of artifacts.
+<li><a href="tutorial/build-repository.html">Building a repository</a></li>
+show how to build your own enterprise repository.
+</ul>
</textarea>
<script type="text/javascript">xooki.postProcess();</script>
</body>
Modified: incubator/ivy/trunk/doc/doc/use/cachepath.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/use/cachepath.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/use/cachepath.html (original)
+++ incubator/ivy/trunk/doc/doc/use/cachepath.html Sat Jan 6 09:23:39 2007
@@ -19,7 +19,7 @@
<li>if the artifact is not local, the location from within the cache is used</li>
<li>if the artifact is a local artifact, it's original location is used</li>
</ul>
-Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling [ivy:ant:resolve]. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.
+Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling [[ant:resolve]]. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.
<table class="ant">
<thead>
Modified: incubator/ivy/trunk/doc/doc/use/deliver.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/use/deliver.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/use/deliver.html (original)
+++ incubator/ivy/trunk/doc/doc/use/deliver.html Sat Jan 6 09:23:39 2007
@@ -45,7 +45,7 @@
The delivered ivy file will update its dependency revisions with those given here.
<h2>deliver and publish</h2>
-The deliver task is most of the time not called explicitly, but rather called automatically by the [ivy:ant: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.
+The deliver task is most of the time not called explicitly, but rather called automatically by the [[ant: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, ...).
Modified: incubator/ivy/trunk/doc/doc/use/postresolvetask.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/use/postresolvetask.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/use/postresolvetask.html (original)
+++ incubator/ivy/trunk/doc/doc/use/postresolvetask.html Sat Jan 6 09:23:39 2007
@@ -10,9 +10,9 @@
These tasks are:
<ul>
-<li>[ivy:ant:retrieve]</li>
-<li>[ivy:ant:cachefileset]</li>
-<li>[ivy:ant:cachepath]</li>
+<li>[[ant:retrieve]]</li>
+<li>[[ant:cachefileset]]</li>
+<li>[[ant:cachepath]]</li>
</ul>
All these tasks will trigger automatically a resolve if:
@@ -21,7 +21,7 @@
<li>organisation and module are not set</li>
</ul>
-Since Ivy 1.4, there are two ways to run a [ivy:ant:resolve]: with an ivy file, or with the inline mode.
+Since Ivy 1.4, there are two ways to run a [[ant:resolve]]: with an ivy file, or with the inline mode.
When you call resolve with an ivy file, the default for it is to keep the resolved data for use by the subsequent post resolve tasks. When you run an inline resolve, the default is not to keep the data. Youo can override this behaviour by setting the keep attribute as you like.
If you want to to reuse the resolved data obtained through a call to resolve in another build (i.e. not the current one), then you have to set the organisation and module attributes. This work only if the cache was not cleaned since your last resolve call. This does not work with inline calls, which must be performed in the same build.
Modified: incubator/ivy/trunk/doc/doc/use/repreport.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/use/repreport.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/use/repreport.html (original)
+++ incubator/ivy/trunk/doc/doc/use/repreport.html Sat Jan 6 09:23:39 2007
@@ -8,7 +8,7 @@
<textarea id="xooki-source">
Generates reports about dependencies among several modules in the repository (repreport stands for repository report).<span class="since">since 1.4</span>
-This task is similar to the [ivy:ant:report] task, except that instead of working on a single module you just resolved, it works with a set of modules in your repository.
+This task is similar to the [[ant:report]] task, except that instead of working on a single module you just resolved, it works with a set of modules in your repository.
Note that the set of modules for which you generate the report is determined by setting organisation module and revision and using a matcher, but also by the dependencies of these modules. No dependency is excluded.
Modified: incubator/ivy/trunk/doc/doc/use/retrieve.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/doc/use/retrieve.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/doc/use/retrieve.html (original)
+++ incubator/ivy/trunk/doc/doc/use/retrieve.html Sat Jan 6 09:23:39 2007
@@ -8,7 +8,7 @@
<textarea id="xooki-source">
The retrieve task copies resolved dependencies anywhere you want in your file system.
-This is a <a href="../../doc/use/postresolvetask.html">post resolve task</a>, with all the behaviour and attributes common to all post resolve tasks.
+This is a [[ant:postresolvetask post resolve task]], with all the behaviour and attributes common to all post resolve tasks.
<span class="since">since 1.4</span> This task can even be used to synchronize the destination directory with what should actually be in according to the dependency resolution. This means that by setting sync="true", Ivy will not only copy the necessary files, but it will also remove the files which do not need to be there.
@@ -24,7 +24,7 @@
<li>if the artifact is not local, the location from within the cache is used</li>
<li>if the artifact is a local artifact, it's original location is used</li>
</ul>
-Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling [ivy:ant:resolve]. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.
+Note that if resolve has been called separately, the copy to the cache may have occur normally if useOrigin was not set when calling [[ant:resolve]]. If resolve has not been called, it will be called automatically with useOrigin set to the value specified on this task.
<table class="ant">
<thead>
Modified: incubator/ivy/trunk/doc/get-involved.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/get-involved.html?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/get-involved.html (original)
+++ incubator/ivy/trunk/doc/get-involved.html Sat Jan 6 09:23:39 2007
@@ -13,6 +13,7 @@
First, [[download]] and use it, subscribe to the [[mailing-lists]], and answer to other user questions. You can also browse [[issues jira issues]], vote for the one you are most interested in, add your comments and feedback. You can also very easily contribute to the [[wiki]].
When you browse the documentation, whenever you see something that could be improved, feel free to edit it and provide a documentation patch. It's very easy if you browse the documentation offline (in the doc directory if you check out Ivy from svn), you will see a small toolbar at the upper left of the page, which allows you to edit the page. Then all you have to do is attach your modification as a patch to a new issue in JIRA.
+<i>If you are interested in contributing documentation, read [[write-doc this page]].</i>
You can also provide brand new documentation pages, tutorials, demo, or even links to a tutorial on your own blog.
Modified: incubator/ivy/trunk/doc/toc.json
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/toc.json?view=diff&rev=493514&r1=493513&r2=493514
==============================================================================
--- incubator/ivy/trunk/doc/toc.json (original)
+++ incubator/ivy/trunk/doc/toc.json Sat Jan 6 09:23:39 2007
@@ -943,7 +943,14 @@
"id":"get-involved",
"title":"Get Involved",
"children": [
+ {
+ "id":"write-doc",
+ "title":"Writing documentation",
+ "children": [
+ ]
+,
+ "level":0 }
]
},
{
Added: incubator/ivy/trunk/doc/write-doc.html
URL: http://svn.apache.org/viewvc/incubator/ivy/trunk/doc/write-doc.html?view=auto&rev=493514
==============================================================================
--- incubator/ivy/trunk/doc/write-doc.html (added)
+++ incubator/ivy/trunk/doc/write-doc.html Sat Jan 6 09:23:39 2007
@@ -0,0 +1,31 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <script type="text/javascript">var xookiConfig = {level: 0};</script>
+ <script type="text/javascript" src="xooki/xooki.js"></script>
+</head>
+<body>
+ <textarea id="xooki-source">
+Writing documentation for Ivy is pretty simple.
+
+The documentation engine used is called <a href="http://xooki.sourceforge.net">xooki</a>, and allows to edit pages while you browse them as soon as you browse them offline (and thus can actually save your modifications).
+
+When you browse the doc offline (by checking out the [[svn:doc]] directory for instance), you will see a small toolbar at the uper right, allowing to edit the page, save it, move the page in the TOC, create a child, and so on. When you choose edit you will see a pretty familiar textbox where you can edit the page source.
+
+The source uses a format very familiar to those who sometimes write html. Indeed any html is allowed. But you also have some shortcuts and neat syntax.
+
+First, line breaks are automatically recognized, so you don't have to put br everywhere.
+Another interesting thing is the code fragment:
+<code>
+<code>
+any text including <tags/>
+</code>
+</code>
+Very helpful to avoid escaping all xml with lt and gt.
+
+Finally, URLs are automatically recognized and convert to links, jira issues like IVY-202 are recognized too, and you can use a neat format to reference any ant ivy ant task like [[ant:import]], or also reference svn page easily like [[svn:build.xml this link to build.xml]]. And you can easily link to another page by providing its id (i.e. its url without the base and the .html) like the [[index]] or the [[doc/reference]].
+
+And do not forget to save your changes before the page! Then you can use your favorite IDE and compute a patch for what you changed, and submit this patch by attaching it to a jira issue, or simply sending it to the ivy-dev [[mailing-lists mailing list]].</textarea>
+<script type="text/javascript">xooki.postProcess();</script>
+</body>
+</html>