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>
