Document locale convention in Tiles def file names

In Tiles v3 integration, underscores in filenames are
intended to identify the definition locale. This behavior
is now documented in order to avoid unexpected results
with filenames like tiles_definitions.xml.

This commit also updates Tiles v2 references to Tiles v3
in the Spring reference documentation.

Issue: SPR-11491

build.gradle

@@ -97,6 +97,7 @@ configure(allprojects) { project ->
 		"http://commons.apache.org/proper/commons-codec/apidocs/",
 		"http://commons.apache.org/proper/commons-dbcp/apidocs/",
 		"http://portals.apache.org/pluto/portlet-2.0-apidocs/",
+		"http://tiles.apache.org/tiles-request/apidocs/",
 		"http://tiles.apache.org/framework/apidocs/",
 		"http://aopalliance.sourceforge.net/doc/",
 		"http://www.eclipse.org/aspectj/doc/released/aspectj5rt-api/",

spring-webmvc-tiles3/src/main/java/org/springframework/web/servlet/view/tiles3/TilesConfigurer.java

 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -100,6 +100,20 @@ import org.springframework.web.context.ServletContextAware;
  * The values in the list are the actual Tiles XML files containing the definitions.
  * If the list is not specified, the default is {@code "/WEB-INF/tiles.xml"}.
  *
+ * <p>Note that in Tiles 3 an underscore in the name of a file containing Tiles
+ * definitions is used to indicate locale information, for example:
+ *
+ * <pre class="code">
+ * &lt;bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles3.TilesConfigurer">
+ *   &lt;property name="definitions">
+ *     &lt;list>
+ *       &lt;value>/WEB-INF/defs/tiles.xml&lt;/value>
+ *       &lt;value>/WEB-INF/defs/tiles_fr_FR.xml&lt;/value>
+ *     &lt;/list>
+ *   &lt;/property>
+ * &lt;/bean>
+ * </pre>
+ *
  * @author mick semb wever
  * @author Rossen Stoyanchev
  * @since 3.2

src/asciidoc/index.adoc

@@ -33380,17 +33380,11 @@ This section focuses on Spring's support for Tiles v3 in the
 ====
 
 
-
 [[view-tiles-dependencies]]
 ==== Dependencies
-To be able to use Tiles you have to have a couple of additional dependencies included in
-your project. The following is the list of dependencies you need.
-
-* `Tiles version 2.1.2 or higher`
-* `Commons BeanUtils`
-* `Commons Digester`
-* `Commons Logging`
-
+To be able to use Tiles, you have to add a dependency on Tiles version 3.0.1 or higher
+and http://tiles.apache.org/framework/dependency-management.html[its transitive dependencies]
+to your project.
 
 
 [[view-tiles-integrate]]
@@ -33403,7 +33397,7 @@ look at the following piece of example ApplicationContext configuration:
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
 ----
-	<bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles2.TilesConfigurer">
+	<bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles3.TilesConfigurer">
 		<property name="definitions">
 			<list>
 				<value>/WEB-INF/defs/general.xml</value>
@@ -33424,6 +33418,31 @@ Spring web application. To be able to use the views you have to have a `ViewReso
 just as with any other view technology used with Spring. Below you can find two
 possibilities, the `UrlBasedViewResolver` and the `ResourceBundleViewResolver`.
 
+You can specify locale specific Tiles definitions by adding an underscore and then
+the locale. For example:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+	<bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles3.TilesConfigurer">
+		<property name="definitions">
+			<list>
+				<value>/WEB-INF/defs/tiles.xml</value>
+				<value>/WEB-INF/defs/tiles_fr_FR.xml</value>
+			</list>
+		</property>
+	</bean>
+----
+
+With this configuration, `tiles_fr_FR.xml` will be used for requests with the `fr_FR` locale,
+and `tiles.xml` will be used by default.
+
+[NOTE]
+====
+Since underscores are used to indicate locales, it is recommended to avoid using
+them otherwise in the file names for Tiles definitions.
+====
+
 
 [[view-tiles-url]]
 ===== UrlBasedViewResolver
@@ -33435,7 +33454,7 @@ resolve.
 [subs="verbatim,quotes"]
 ----
 	<bean id="viewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolver">
-		<property name="viewClass" value="org.springframework.web.servlet.view.tiles2.TilesView"/>
+		<property name="viewClass" value="org.springframework.web.servlet.view.tiles3.TilesView"/>
 	</bean>
 ----
 
@@ -33458,10 +33477,10 @@ viewnames and viewclasses the resolver can use:
 [subs="verbatim,quotes"]
 ----
 	...
-	welcomeView.(class)=org.springframework.web.servlet.view.tiles2.TilesView
+	welcomeView.(class)=org.springframework.web.servlet.view.tiles3.TilesView
 	welcomeView.url=welcome (this is the name of a Tiles definition)
 
-	vetsView.(class)=org.springframework.web.servlet.view.tiles2.TilesView
+	vetsView.(class)=org.springframework.web.servlet.view.tiles3.TilesView
 	vetsView.url=vetsView (again, this is the name of a Tiles definition)
 
 	findOwnersForm.(class)=org.springframework.web.servlet.view.JstlView
@@ -33500,7 +33519,7 @@ per preparer name (as used in your Tiles definitions).
 [source,xml,indent=0]
 [subs="verbatim,quotes"]
 ----
-	<bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles2.TilesConfigurer">
+	<bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles3.TilesConfigurer">
 		<property name="definitions">
 			<list>
 				<value>/WEB-INF/defs/general.xml</value>
@@ -33513,7 +33532,7 @@ per preparer name (as used in your Tiles definitions).
 
 		<!-- resolving preparer names as Spring bean definition names -->
 		<property name="preparerFactoryClass"
-				value="org.springframework.web.servlet.view.tiles2.SpringBeanPreparerFactory"/>
+				value="org.springframework.web.servlet.view.tiles3.SpringBeanPreparerFactory"/>
 
 	</bean>
 ----