svn commit: r329588 - /jakarta/velocity/core/trunk/WHY_TWO_JARS.txt

[he...@apache.org]

Author: henning
Date: Sun Oct 30 08:34:30 2005
New Revision: 329588

URL: http://svn.apache.org/viewcvs?rev=329588&view=rev
Log:
update docs about the two jars.

Modified:
    jakarta/velocity/core/trunk/WHY_TWO_JARS.txt

Modified: jakarta/velocity/core/trunk/WHY_TWO_JARS.txt
URL: http://svn.apache.org/viewcvs/jakarta/velocity/core/trunk/WHY_TWO_JARS.txt?rev=329588&r1=329587&r2=329588&view=diff
==============================================================================
--- jakarta/velocity/core/trunk/WHY_TWO_JARS.txt (original)
+++ jakarta/velocity/core/trunk/WHY_TWO_JARS.txt Sun Oct 30 08:34:30 2005
@@ -1,32 +1,70 @@
 WHY ARE THERE TWO JARS?  WHAT'S THE DIFFERENCE?
+===============================================
+
+We are including two jars with the Velocity distribution. This
+document describes the differences and what they are intended for.
+
+Both jars are included in the root directory of the Velocity
+distribution.
+
+CAVEAT: Up and including the 1.4 release of Velocity, there was a
+wealth of different jars including J2EE code, containing just the
+runtime or the tools. This lead to some confusion about the naming and
+the purpose of the various jars.
+
+Starting with the 1.5 release of Velocity, there is now only one jar,
+velocity-<version>.jar which contains all Velocity code and a second
+jar, velocity-dep-<version>.jar, which contains all Velocity code and
+its external dependencies. 
 
-Continuing what we started with the 1.2 release,
-we are including two jars with the distribution.
 
 velocity-<version>.jar
-----------------
-  This jar does not include any external dependencies that Velocity
-  depends on.  It does include the core Velocity Template engine,
-  all supporting classes, Anakia and Texen.
-
-  All external dependencies needed by Velocity, such as the 
-  jakarta-commons-collection classes, Jakarta Avalon Logkit, or 
-  Jakarta ORO are *NOT* included. 
-
-  We do this to allow you to use whatever version of
-  collections, logkit, etc that you wish w/o fear of collision.
-  
-  For your convenience, these jars are included with the 
-  distribution package, in the build/lib directory.
+----------------------
+
+  This jar contains only the velocity specific code in the
+  org.apache.velocity.* packages. 
+
+  If you want to integrate Velocity in your own code or a larger
+  project, we recommend that you use this jar.
+
+  It has some external dependencies which are listed in the developer
+  docs. Make sure that you have these dependencies present in your
+  application.
+
+  Please see the developers guide for more information.
 
-  The can also be found at respective project sites.
 
 velocity-dep-<version>.jar
---------------------
-  This is a Velocity jar that includes all dependencies that 
-  were included with previous distribution jars.  It is included
-  as a convenience to allow you to drop this distribution 
-  in place of existing 1.1 or 1.2 distributions.
+--------------------------
+
+  This jar is intended to be used when you do standalone development
+  with Velocity. It contains all of the core Velocity code (runtime,
+  anakia, texen and their respective ant tasks) and also all external
+  dependencies from other jars, repackaged into a single jar. Currently
+  that is:
+
+  oro           org.apache.oro.* packages,
+                from http://jakarta.apache.org/oro/
+
+  commons-lang  org.apache.commons.lang.* packages,
+                from http://jakarta.apache.org/commons/lang/
+
+  Avalon Logkit org.apache.log.* packages
+
+  and a subset of
+
+  commons-collections org.apache.commons.collections.* packages
+                      from http://jakarta.apache.org/commons/collections/
+
+  These classes are strictly intended for Velocity use! If you want to use
+  the velocity-dep jar, do not rely on any of the other classes being present.
+  We reserve the right to change the supporting classes (those not in the
+  org.apache.velocity.* packages) at any time for any release.
 
-Please see the developers guide for more information.
+  When using this jar without anything else, you are also restricted to
+  using the Avalon Logkit for logging (or JDK 1.4 logging if you run under
+  JDK 1.4 or newer).
 
+  This jar should only be used for the Velocity runtime. The various tools
+  (Anakia, Texen, Webmacro converter) have additional dependencies that are
+  not inside this jar!



---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org