Return-Path: Delivered-To: apmail-velocity-commits-archive@minotaur.apache.org Received: (qmail 23733 invoked from network); 26 Nov 2010 12:19:28 -0000 Received: from unknown (HELO mail.apache.org) (140.211.11.3) by 140.211.11.9 with SMTP; 26 Nov 2010 12:19:28 -0000 Received: (qmail 69361 invoked by uid 500); 26 Nov 2010 12:19:27 -0000 Delivered-To: apmail-velocity-commits-archive@velocity.apache.org Received: (qmail 69327 invoked by uid 500); 26 Nov 2010 12:19:26 -0000 Mailing-List: contact commits-help@velocity.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@velocity.apache.org Delivered-To: mailing list commits@velocity.apache.org Received: (qmail 69315 invoked by uid 99); 26 Nov 2010 12:19:25 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 26 Nov 2010 12:19:25 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 26 Nov 2010 12:19:19 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id CBFA323888C2; Fri, 26 Nov 2010 12:17:45 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1039326 - in /velocity/engine/branches/2.0_Exp/src/site: apt/release.apt site.xml xdoc/build.xml xdoc/developer-guide.xml xdoc/getting-started.xml xdoc/jar-dependencies.xml xdoc/user-guide.xml Date: Fri, 26 Nov 2010 12:17:45 -0000 To: commits@velocity.apache.org From: apetrelli@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20101126121745.CBFA323888C2@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: apetrelli Date: Fri Nov 26 12:17:45 2010 New Revision: 1039326 URL: http://svn.apache.org/viewvc?rev=1039326&view=rev Log: VELOCITY-788 Updated existing files and added release process guide. Added: velocity/engine/branches/2.0_Exp/src/site/apt/release.apt Modified: velocity/engine/branches/2.0_Exp/src/site/site.xml velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml velocity/engine/branches/2.0_Exp/src/site/xdoc/getting-started.xml velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml Added: velocity/engine/branches/2.0_Exp/src/site/apt/release.apt URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/apt/release.apt?rev=1039326&view=auto ============================================================================== --- velocity/engine/branches/2.0_Exp/src/site/apt/release.apt (added) +++ velocity/engine/branches/2.0_Exp/src/site/apt/release.apt Fri Nov 26 12:17:45 2010 @@ -0,0 +1,348 @@ +~~ $Id$ +~~ +~~ Licensed to the Apache Software Foundation (ASF) under one +~~ or more contributor license agreements. See the NOTICE file +~~ distributed with this work for additional information +~~ regarding copyright ownership. The ASF licenses this file +~~ to you under the Apache License, Version 2.0 (the +~~ "License"); you may not use this file except in compliance +~~ with the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, +~~ software distributed under the License is distributed on an +~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +~~ KIND, either express or implied. See the License for the +~~ specific language governing permissions and limitations +~~ under the License. +~~ + ----------- + Release Process + ----------- + +Velocity Engine Release Process + + Here you will find the steps to create releases for Velocity Engine. + +Prerequisites + + To create a release you have to install: + + * {{{http://java.sun.com/j2se/1.5.0/}Java 5.0}}. If you are using a newer + version of Java, it is suggested to <> + when calling Maven, so it points to an instance of Java 5.0; + + * {{{http://maven.apache.org/}Maven 2}}; + + * {{{http://www.gnupg.org/}GnuPG}}; + + * {{{http://www.openssh.com/}OpenSSH}}; + +One-time operations + + These operations need to be performed only one time. + +* Create and publish your GPG key + + To create a GPG key, follow the + {{{http://www.apache.org/dev/openpgp.html}guidelines}}. + Insert in the file you find on people.apache.org at the directory: + +------------------------------------- +/www/www.apache.org/dist/velocity/ +------------------------------------- + + Publish your GPG key in a PGP key server, such as + {{{http://pgp.mit.edu/} MIT Keyserver}}. + +* Create and upload yout SSH key + + * Generate your SSH key (in this case we will use RSA encryption): + +--------------------------------- +ssh-keygen -t rsa +--------------------------------- + + * Copy your public key to the server: + +-------------------------------------- +scp ~/.ssh/id_rsa.pub user@people.apache.org:.ssh/authorized_keys +-------------------------------------- + + * Try to login: + +--------------------------------- +ssh user@people.apache.org +--------------------------------- + + If it does not ask you a password, everything is ok. + +* Modify <<>> + + Your <<>> must be modified to allow deployment. + + This is the minimal configuration, obviously if you already have a <<>> file, + you must edit it: + +--------------------------- + + + + apache-site + YOUR_APACHE_USERNAME + 664 + 775 + + + apache.snapshots.https + YOUR_APACHE_USERNAME + YOUR_APACHE_PASSWORD + + + apache.releases.https + YOUR_APACHE_USERNAME + YOUR_APACHE_PASSWORD + + + + + release + + YOUR_SECRET_PHRASE + + + + + +--------------------------- + +Repeatable operations + + These steps must be performed <> release. + +* Prepare the release tag + + To prepare the release Subversion tag, check out the branch/trunk from where + you are preparing the release and type: + +----------------------------------- +mvn release:prepare -Dusername=YOUR_SVN_USER -Dpassword=YOUR_SVN_PASSWORD +----------------------------------- + + The plugin interactively will ask you the version to release, the Subversion + tag to use and the next snapshot version. It is reccomended to use the tag: + <> (the default). + +* Perform the Release + + To perform the release, i.e. creating and deploying Maven artifacts, use: + +----------------------------------- +mvn release:perform +----------------------------------- + +* Close the staging repository + + Login to {{{https://repository.apache.org using} Nexus repository}} your Apache LDAP credentials. + Click on "Staging". Then click on "velocity" in the list of repositories. + In the panel below you should see an open repository that is linked to your username and ip. + Right click on this repository and select "Close". + This will close the repository from future deployments and make it available for others to view. + If you are staging multiple releases together, skip this step until you have staged everything. + Enter the name and version of the artifact being released in the "Description" field and then click "Close". + This will make it easier to identify it later. + +* Verify the staged artifacts + + If you click on your repository, a tree view will appear below. + You can then browse the contents to ensure the artifacts are as you expect them. + Pay particular attention to the existence of *.asc (signature) files. + If the you don't like the content of the repository, right click your repository and choose "Drop". + You can then rollback your release and repeat the process. + + Note the repository URL, you will need this in your vote email. + +* Digest and upload assemblies + + * Go into the release assembly target directory: + +----------------------------------- +cd target/checkout/assembly/target/assembly/out +----------------------------------- + + * Create MD5 and SHA1 files for each files (including ASC files). You can do + it with this simple shell script: + +----------------------------------- +#!/bin/sh + +for fileitem in * +do + openssl md5 < $fileitem > $fileitem.md5 + openssl sha1 < $fileitem > $fileitem.sha1 +done +----------------------------------- + + * Upload everything to the build site: + +----------------------------------- +scp * user@people.apache.org:/www/people.apache.org/builds/velocity-engine-parent/${version} +----------------------------------- + +* Release the JIRA version + + * In JIRA go to the version that you want to release and release it. + + * Create a new version, if it has not been done before. + + * Create the release notes and <> that it uses. + +* Send announcement for the test build + + In <> send an announcement for the test build: + +----------------------------------- +Subject: [ANNOUNCE] Velocity Engine ${version} test build available + +The test build of Velocity Engine ${version} is available. + + +No determination as to the quality ('alpha,' 'beta,' or 'GA') of Velocity Engine +${version} has been made, and at this time it is simply a "test build". We +welcome any comments you may have, and will take all feedback into +account if a quality vote is called for this build. + +Release notes: + +* ${jira.release.notes} + +Distribution: + + * http://people.apache.org/builds/velocity-engine-parent/${version}/ + +Maven 2 staging repository: + + * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/ + +A vote regarding the quality of this test build will be initiated +within the next couple of days. +----------------------------------- + +* Call for a vote + + A few days after the test build announcement, call for a vote in + <>. + +----------------------------------- +Subject: [VOTE] ${version} Release Quality + +The Velocity Engine ${version} test build has been available since ${testBuildDate}. + +Release notes: + +* ${jira.release.notes} + +Distribution: + + * http://people.apache.org/builds/velocity-engine-parent/${version}/ + +Maven 2 staging repository: + + * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/ + +If you have had a chance to review the test build, please respond with +a vote on its quality: + + [ ] Leave at test build + [ ] Alpha + [ ] Beta + [ ] General Availability (GA) + + +Everyone who has tested the build is invited to vote. Votes by PMC +members are considered binding. A vote passes if there are at least +three binding +1s and more +1s than -1s. +----------------------------------- + +* Post-vote operations + + After a vote is finished, and it has been decided that is + <>, there is the need of a post-vote process. + +** Promote staged artifacts + + Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users. + + Login to {{{https://repository.apache.org}Nexus repository}} again. + Click on "Staging" and then on the repository with id "velocity-staging". + Find your closed staging repository, right click on it and choose "Promote". + Select the "Releases" repository and click "Promote". + + Next click on "Repositories", select the "Releases" repository + and validate that your artifacts exist as you expect them. + +** Move assemblies + + * Move assemblies to the Apache distribution mirrors: + +------------------------------------------- +ssh user@people.apache.org + +cd /www/people.apache.org/builds/velocity/${version} +mkdir /www/www.apache.org/dist/velocity/v${version}/ +cp * /www/www.apache.org/dist/velocity/v${version}/ +------------------------------------------- + +** Update the site + + * Wait 24 hours to let the mirror sync to the release and then update the + site. In particular you have to update the index and the download pages: + +------------------------------------------------ +https://svn.apache.org/repos/asf/velocity/site/site/xdoc/download.xml +https://svn.apache.org/repos/asf/velocity/site/site/news.xml +------------------------------------------------ + + Build and publish the site: + +-------------------------------------- +mvn site +mvn site:deploy +-------------------------------------- + +** Send announcement + + Finally, send an an announcement to the <> and <>: + +-------------------------------------- +Subject: [ANNOUNCE] Velocity Engine ${version} ${quality} released + +The Apache Velocity team is pleased to announce the release of Velocity Engine ${version} +${quality}. + +Velocity Engine ${version} is available in a binary and a source distribution. + +http://velocity.apache.org/download.html + +It is also available in the central Maven repository under Group ID +"org.apache.velocity". + +The 2.0.x series of the Apache Velocity Engine framework has a minimum +requirement of the following specification versions: + +* Java Standard Edition (Java SE) 1.6 + +The release notes are available online at: + +* ${jira.release.notes} + +Please feel free to test the distribution and post your comments to +the user list, or, if appropriate, file a ticket with JIRA. +-------------------------------------- + + <> \ No newline at end of file Modified: velocity/engine/branches/2.0_Exp/src/site/site.xml URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/site.xml?rev=1039326&r1=1039325&r2=1039326&view=diff ============================================================================== --- velocity/engine/branches/2.0_Exp/src/site/site.xml (original) +++ velocity/engine/branches/2.0_Exp/src/site/site.xml Fri Nov 26 12:17:45 2010 @@ -87,6 +87,7 @@ + Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml?rev=1039326&r1=1039325&r2=1039326&view=diff ============================================================================== --- velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml (original) +++ velocity/engine/branches/2.0_Exp/src/site/xdoc/build.xml Fri Nov 26 12:17:45 2010 @@ -15,7 +15,7 @@ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations - under the License. + under the License. --> @@ -30,166 +30,51 @@

-Velocity runs on a variety of platforms that have installed the Java 2 -Virtual Machine. The J2SDK is required for users who want to compile +Velocity runs on a variety of platforms that have installed the Java +Virtual Machine. The Java Development Kit version 1.6 is required for users who want to compile Velocity from its source code.

Everything required to build Velocity comes with the distribution, which can be obtained from Subversion or +href="http://svn.apache.org/repos/asf/velocity/engine/">Subversion or from the nightly -snapshots. However, you will need to install Ant to build the Velocity sources.

+href="http://velocity.apache.org/download.cgi#Engine">main distribution. +However, you will need to install Maven to build the Velocity sources.

-

Ant is also an Apache project, and can be -found here. To build Apache Velocity, you need at least Version 1.6 of Apache Ant. +

Maven is also an Apache project. +To build Apache Velocity, you need at least Version 2.2.1 of Apache Maven.

-

-The directory tree of the distribution looks like: -

- - -

-To make building Velocity easy and consistent, we require an Apache project -called Ant version 1.6 or -higher to perform the build process. We assume that you have followed -Ant's installation instructions and have it properly installed. +To build Velocity we require Maven +version 2.2.1 or higher (Mave 3 can be used too) to perform the build process. +We assume that you have followed Maven's installation instructions and have it properly installed.

-Velocity requires JDK 1.4 or greater to compile. It's possible to use JDK 1.3 -to compile but several useful features will not be included. Velocity requires -a minimum of JDK 1.3 to run. +Velocity requires JDK 1.6 or greater to compile.

Finally, if you wish to modify Velocity's grammar you will need to a tool -called JavaCC. We recommend +called JavaCC. We recommend version 3.2 or greater (for compatibility with JDK 1.5 syntax changes).

-
- -

Velocity requires various third party jar files for compiling and -for running. Not all jar files are required in all cases. When -building, all dependencies will be downloaded automatically. You can -control the download with the skip.jar.loading and -force.jar.loading properties in the -build.properties file. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
JarPurposeRequired at Runtime?
antlr-2.7.5.jarXML parsing (XPath queries in particular)Only for Anakia
avalon-logkit-2.1.jarPossible means of loggingNo
commons-collection-3.1.jarUsed in parsing configurationYes
commons-lang-2.1.jarVarious String utility functionsYes
commons-logging-1.1.jarTo redirect log output to commons-loggingOnly for those using commons-logging
jdom-1.0.jarXML parsingOnly for Anakia
log4j.1.2.12.jarPossible means of loggingNo
oro-2.0.8.jarFor regular expression parsing in tests and event handlersOnly for reference escaping event handlers
servletapi-2.3.jarFor the deprecated VelocityServlet and redirecting log output to the servlet log.Only for VelocityServlet or ServletLogChute
werken-xpath-0.9.4.jarXML parsingOnly for Anakia
junit-3.8.1.jarFor running unit testsNo
hsqldb-1.7.1.jarFor running database related unit testsNo
ant.jarRequired for compilation. Provided by the ant build tool.No
- - -

-Note that you can always create a jar with all required run-time dependencies by executing the -jar-dep task. -

- -
-

In each case below, it is assumed that you were successful in getting -the distribution from Subversion or as a nightly build, and with the latter, +the distribution from Subversion, and with the latter, were successful in unpacking. Also, it is assumed that you are starting in the 'velocity' directory, the root of the distribution tree. All directory references will be relative to 'velocity'. @@ -201,151 +86,27 @@ build). Then, to build the jar fi

-Executing this script will create a bin directory -within the Velocity distribution directory. The bin -directory will contain the compiled class files (inside a -classes directory) as well as a -velocity-XX.jar file, where XX is the current -version number. Be sure to update your classpath to include Velocity's -.jar file. +Executing this script will create a target directory +within the Velocity distribution directory. Each subdirectory +containing a module of Velocity will contain a "target" directory +too, containing all built jars. In the "velocity-assembly" module +you will find built distributions.

-Note that to build any of the specific build targets simply add -the target name to the command line. For example, to build the Javadoc -API documentation: +Refer to Maven documentation for all phases you can invoke.

- - - -

Some of the most useful targets are: -

- -
    -
  • - jar builds the complete Velocity jar in the - bin directory. This jar will be called 'velocity-X.jar', - where 'X' is the current version number. This jar does not include - necessary dependencies for Velocity. If you use this - target, you must put the required dependent jars in your CLASSPATH (or WEB-INF/lib). - For convenience, you can use the jar-dep target to build - a jar with all required dependent classes included. -
    • -
  • - jar-dep builds the complete Velocity jar in - the bin directory. -
    • -
  • - clean deletes all generated classes, jars, documentation, and other files. -
    • -
  • - real-clean like clean but also deletes all downloaded jars. -
    • -
  • - docs builds these docs in the docs directory - using Velocity's Anakia XML transformation tool. - Allows you to use - Velocity templates in place of stylesheets - - give it a try! -
    • -
  • - examples builds the example code in the example programs - found in the examples directory. -
    • -
  • - jar-src bundles all the Velocity source code into a single - jar, placed in the bin directory. -
    • -
  • - javadocs builds the Javadoc class documentation in the - docs/api directory -
    • -
  • - package will generate the complete Velocity distribution package. -
    • -
  • - parser will compile the JavaCC parser files from src/Parser.jjt into - the appropriate Java source files. Requires JavaCC 3.2+ to be installed, and the - property javacc.home to contain a path to the installed JavaCC directory. -
    • -
  • - test (after jar) will test Velocity against its testbed - suite of test routines. -
    • -
- - -

-Velocity should build 'out of the box', independent of your classpath. -If you get an error building Velocity, try a different nightly build (as -sometimes we make a mistake and the Subversion at the time of the nightly -snapshot isn't complete) or refresh from Subversion (you might have gotten a -Subversion snapshot while a developer was checking things in.) -

- -

-If the problems persist, do not hesitate to ask the Velocity community +If you find a problem, do not hesitate to ask the Velocity community via our mail lists. They can be found here. -

- -
- -
- -

-The Velocity developers use an automated test facility, and it is -included in the distribution. You can use it to make sure that all is -well with your build of Velocity. -

- -

The tests are run with the ant task <junit>. For ant 1.6, this task requires that -junit.jar be copied into the lib subdirectory of your -ant directory. For ant 1.7 this is not required. -

- -

-To run the test suite, simply use the build target -test when you build: +href="http://velocity.apache.org/contact.html">here.

- - -

-If all is well, you should see output similar to: -

- - - -

-Note that the number of tests may vary from those shown above, but if -you see 'OK' after the tests are run, all is well. -

Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml?rev=1039326&r1=1039325&r2=1039326&view=diff ============================================================================== --- velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml (original) +++ velocity/engine/branches/2.0_Exp/src/site/xdoc/developer-guide.xml Fri Nov 26 12:17:45 2010 @@ -15,7 +15,7 @@ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations - under the License. + under the License. --> @@ -163,8 +163,8 @@ more detail on the various options.

You can download the latest release version of - Velocity - or Velocity Tools + Velocity + or Velocity Tools from the main Apache Velocity download site. For Velocity itself, source is included with the binary download.

@@ -571,7 +571,7 @@ in the VTL #foreach() direc here. Velocity will internally wrap your array in a class that provides an Iterator interface, but that shouldn't concern you as the programmer, or the template author. Of more interest, is the fact that Velocity will now -allow template authors to treat arrays as fixed-length lists (as of Velocity 1.6). +allow template authors to treat arrays as fixed-length lists (as of Velocity 1.6). This means they may call methods like size(), isEmpty() and get(int) on both arrays and standard java.util.List instances without concerning themselves about the difference. @@ -1128,10 +1128,10 @@ template content other than template fil Exceptions

-Velocity may throw one of several exceptions during the parse / merge cycle. These +Velocity may throw one of several exceptions during the parse / merge cycle. These exceptions extend RuntimeException and do not need to explicitly caught, although each includes specific properties that may help in presenting -useful error messages to the end user. The exceptions +useful error messages to the end user. The exceptions are found in the package org.apache.velocity.exception and are:

@@ -1311,15 +1311,15 @@ Velocity contains a fine-grained event h

org.apache.velocity.app.event.IncludeEventHandler

-The IncludeEventHandler can be used to modify the template that is included +The IncludeEventHandler can be used to modify the template that is included in a page with #include or #parse. For example, this may be used to make all includes relative to the current directory or to prevent access to unauthorized resources. Multiple IncludeEventHandler's may be chained, with the return value of the final call used as the name of the template to retrieve. 
 public IncludeEventHandler extends EventHandler
 {
-    public String includeEvent( String includeResourcePath, 
-                                String currentResourcePath, 
+    public String includeEvent( String includeResourcePath,
+                                String currentResourcePath,
                                 String directiveName );
 }
@@ -1338,21 +1338,21 @@ calls behave will differ per method. (S 
 public InvalidReferenceEventHandler extends EventHandler
 {
-    public Object invalidGetMethod( Context context, 
-                                    String reference, 
-                                    Object object, 
-                                    String property, 
+    public Object invalidGetMethod( Context context,
+                                    String reference,
+                                    Object object,
+                                    String property,
                                     Info info);
 
-    public boolean invalidSetMethod( Context context, 
-                                     String leftreference, 
-                                     String rightreference, 
+    public boolean invalidSetMethod( Context context,
+                                     String leftreference,
+                                     String rightreference,
                                      Info info);
 
-    public Object invalidMethod( Context context, 
-                                 String reference,  
-                                 Object object, 
-                                 String method, 
+    public Object invalidMethod( Context context,
+                                 String reference,
+                                 Object object,
+                                 String method,
                                  Info info);
 }
@@ -1370,13 +1370,13 @@ When a user-supplied method throws an ex and thrown Exception. The handler can either return a valid Object to be used as the return value of the method call or throw the passed-in or new Exception, which will be wrapped and propogated to the user as a -MethodInvocationException. While MethodExceptionEventHandler's can be +MethodInvocationException. While MethodExceptionEventHandler's can be chained only the first handler is actually called -- all others are ignored. 
 public interface MethodExceptionEventHandler extends EventHandler
 {
-    public Object methodException( Class claz, 
-                                   String method, 
+    public Object methodException( Class claz,
+                                   String method,
                                    Exception e )
          throws Exception;
 }
@@ -1392,12 +1392,12 @@ Available implementations include:
 

 A ReferenceInsertionEventHandler allows the
 developer to intercept each write of a reference ($foo) value to the output
-stream and modify that output.  Multiple ReferenceInsertionEventHandler's 
+stream and modify that output.  Multiple ReferenceInsertionEventHandler's
 may be chained with each step potentially altering the inserted reference.
 
 public interface  ReferenceInsertionEventHandler extends EventHandler
 {
-    public Object referenceInsert( String reference, 
+    public Object referenceInsert( String reference,
                                    Object value  );
 }
 

@@ -1460,12 +1460,12 @@ public class Test
     ....
 
     /**
-     * Make a cartridge to hold the event handlers 
+     * Make a cartridge to hold the event handlers
      */
     EventCartridge ec = new EventCartridge();
 
     /*
-     * then register and chain two escape-related handlers 
+     * then register and chain two escape-related handlers
      */
     ec.addEventHandler(new EscapeHtmlReference());
     ec.addEventHandler(new EscapeSqlReference());
@@ -1680,7 +1680,7 @@ runtime log.
 

 
 

-resource.manager.cache.class  
+resource.manager.cache.class
 

 Declares the class to be used
 for resource caching.  The current default is
@@ -1692,7 +1692,7 @@ is 89.  Note that the ConcurrentHashMap 
 

 
 

-resource.manager.defaultcache.size 
+resource.manager.defaultcache.size
     

     Sets the size of the default implementation of the resource
     manager cache size.  The default is 89.
@@ -1824,7 +1824,7 @@ This feature is intended for development
 velocimacro.arguments.strict = false

 When set to true, will throw a ParseErrorException when
 parsing a template containing a macro with an invalid number of arguments.
-Is set to false by default to maintain backwards compatibility with 
+Is set to false by default to maintain backwards compatibility with
 templates written before this feature became available.
 

 
@@ -1862,7 +1862,7 @@ New in Velocity 1.6, when set to true Ve
 defined in the context, or have not been defined with a #set
 directive.  This setting will also throw an exception if an attempt is
 made to call a non-existing property on an object or if the object is
-null.  When this property is true then 
+null.  When this property is true then
 'directive.foreach.skip.invalid' defaults to true,
 but explicitly setting 'directive.foreach.skip.invalid' will
 override this default. For a complete discussion see 
 
 
@@ -65,8 +65,8 @@ Application Guide is highly recommended!
 

     

         You can download the latest release version of
-        Velocity
-        or Velocity Tools
+        Velocity
+        or Velocity Tools
         from the main Apache Velocity download site.  For Velocity itself, source is included with the binary download.
     

 

Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/jar-dependencies.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
- under the License.    
+ under the License.
 -->
 
 
@@ -75,37 +75,9 @@
         
         
           servletapiNo
-          Only needed when the VelocityServlet
-              or ServletLogChute are used.
-              Should normally be supplied by the servlet container.
-              VelocityServlet is deprecated and should
-              be replaced with VelocityViewServlet from the
-              velocity-tools distribution.
-        
-        
-          jdomNo
-          Only required for the deprecated Anakia tool / ant task
-        
-        
-          werken-xpathNo
-          Only required for the deprecated Anakia tool / ant task
-        
-        
-          antlrNo
-          Only required for the deprecated Anakia tool / ant task
-        
-        
-          antNo
-          Only needed for compilation.
-        
-        
-          junitNo
-          Only needed for running the tests during compilation.
-        
-        
-          hsqldbNo
-          Only needed for running the tests during compilation.
+          Only needed when the
+              ServletLogChute is used.
+              Should normally be supplied by the servlet container.
         
       
 
@@ -117,10 +89,7 @@
         you should check if you need to update their versions.
       

 
-      
The auto-generated dependency report lists all mandatory
-         dependencies as compile and all optional dependencies as provided, though
-         it fails to properly reflect the optional nature of the Oro and Commons-Logging dependencies.
-      

+      
Take a look at each module documentation to see all dependencies in detail

     

   
 

Modified: velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml
URL: http://svn.apache.org/viewvc/velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml?rev=1039326&r1=1039325&r2=1039326&view=diff
==============================================================================
--- velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml (original)
+++ velocity/engine/branches/2.0_Exp/src/site/xdoc/user-guide.xml Fri Nov 26 12:17:45 2010
@@ -15,7 +15,7 @@
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
- under the License.    
+ under the License.
 -->
 
 
@@ -37,6 +37,12 @@
         
  • The Mud Store example
    • 
     
 
+
  • What jar should I use?
+    
      
+        
    1. Maven users
      2. 
+        
    2. Other users
      3. 
+    
    
+
    • 
 
  • Velocity Template Language (VTL): An Introduction
    • 
 
  • Hello Velocity World!
    • 
 
  • Comments
    • 
@@ -226,6 +232,75 @@ Hello $customer.Name!
 
 
 
+
+
    
+ 
    
+   Velocity Engine 2.x distribution has several jars, related to the Maven
+   artifacts that are published to the Maven repository.
+ 
    
+ 
+    
    
+     Include the following dependency to your POM file:
+    
    
+    
+  org.apache.velocity
+  velocity-engine-core
+  x.x.x
+]]>
+    
+    
    If you want to connect Velocity log facility to Commons Logging, Log4j or the servlet logger,
+    choose the appropriate dependency:
    
+    
+  org.apache.velocity
+  velocity-engine-commons-logging
+  x.x.x
+
+
+
+  org.apache.velocity
+  velocity-engine-log4j
+  x.x.x
+
+
+
+  org.apache.velocity
+  velocity-engine-servlet
+  x.x.x
+
+]]>
+    
+     
+ 
+	 
    
+	   First of all download Velocity Engine distribution.
+	 
    
+	 
    
+	   If you want to jumpstart your application, simply include velocity-x.x.x.jar
+	   in your classpath: it includes all classes of Velocity Engine (with the exclusion of the examples).
+	   Include all the jars in the "lib" subdirectory too.
+	 
    
+	 
    
+	   The other jars are finely-grained jars that contain only what you might need.
+	 
    
+	 
      
+	 	
    • velocity-engine-core-x.x.x.jar: The main Velocity library. It
+	 	must be included at all times.
      • 
+	 	
    • velocity-engine-commons-logging-x.x.x.jar: It contains the binding to
+	 	Commons Logging, so all log messages will be directed to it. To be used in
+	 	conjunction with Commons Logging (included in "lib" directory).
      • 
+	 	
    • velocity-engine-log4j-x.x.x.jar: It contains the binding to
+	 	Log4j, so all log messages will be directed to it. To be used in
+	 	conjunction with Log4j (included in "lib" directory).
      • 
+	 	
    • velocity-engine-servlet-x.x.x.jar: It contains the binding to
+	 	the servlet logger. To be used in a servlet container.
      • 
+	 
    
+	 
    The extra jars you will always need always are Commons Collections and Commons Lang,
+     included in "lib" directory.
    
+     
+
    
+
 
    
 
  
    
@@ -375,7 +450,7 @@ visible. *# This text is outside the com
 
  
    
     There is a third type of comment, the VTL comment block, which may
-    be used to store any sort of extra information you want to track 
+    be used to store any sort of extra information you want to track
     in the template (e.g. javadoc-style author and versioning information):
  
    
 
@@ -611,7 +686,7 @@ $sun.setPlanets()
  
    
 
  
    
-    Index Notation    
+    Index Notation
     
    
     Using the notation of the form $foo[0] can be used to access a
     given index of an object.  This form is synonymous with calling
@@ -621,7 +696,7 @@ $sun.setPlanets()
     following are valid uses:
  
    
     $foo[0]       ## $foo takes in an Integer look up
-$foo[$i]      ## Using another reference as the index   
+$foo[$i]      ## Using another reference as the index
 $foo["bar"]   ## Passing a string where $foo may be a Map
  
    
     The bracketed syntax also works with Java arrays since Velocity
@@ -632,7 +707,7 @@ $foo["bar"]   ## Passing a string where 
  
    
    The bracketed syntax is valid anywhere .get is valid,
    for example:
- 
       
+ 
    
    $foo.bar[1].junk
 $foo.callMethod()[1]
 $foo["apple"][4]
@@ -769,14 +844,14 @@ Jack is a ${vice}maniac.
       
+#foreach($item in $foo)#end  ## Exception]]>
   
    
     Also, The following statements show examples in which Velocity will
     throw an exception when attempting to call methods or properties
     that do not exist. In these examples $bar contains an object that
     defines a property 'foo' which returns a string, and 'retnull' which
     returns null.
-  
        
+  
    
   
@@ -1576,10 +1651,10 @@ $count
     
    
     The #evaluate directive can be used to dynamically evaluate VTL.  This allows
     the template to evaluate a string that is created at render time.  Such a string might be
-    used to internationalize the template or to include parts of a template from a database.    
+    used to internationalize the template or to include parts of a template from a database.
     
    
 
-    
    The example below will display abc.  
+    
    The example below will display abc.
     
    
 
 
 
- 
+
  
    
 
 
    
@@ -1599,7 +1674,7 @@ $count
     The #define directive lets one assign a block of VTL to a reference.
     
    
 
-    
    The example below will display Hello World!.  
+    
    The example below will display Hello World!.
     
    
 
 
 
- 
+
  
    
 
 
    
@@ -2054,7 +2129,7 @@ ${D}{my:invalid:non:reference}
     
    You can, of course, put your $ or # string directly
     into the context from your java code (e.g. context.put("D","$");)
     to avoid the extra #set() directive in your template(s).  Or, if you are using
-    VelocityTools, you can 
+    VelocityTools, you can
     just use the EscapeTool like this: