Docs: edits to 1.2 documentation updates

documentation/cheatsheets/multiEnvironment/ch26-MultiEnvironment.textile

@@ -1,4 +1,4 @@
-h2. Multi environment
+h2. Multi-environment
 
 *==# Test configuration==*
 *==%test.db=mem==*

documentation/manual/dependency.textile

@@ -1,4 +1,4 @@
-h1. Dependencies management
+h1. Dependency management
 
 Play’s dependency management system allows you to express your application’s external dependencies in a single **dependencies.yml** file. 
 
@@ -34,14 +34,14 @@ The revision can be fixed (1.2, for instance) or dynamic. A dynamic revision exp
 
 For example:
 
-* **[1.0,2.0]** matches all versions greater or equal to 1.0 and lower or equal to 2.0
-* **[1.0,2.0[** matches all versions greater or equal to 1.0 and lower than 2.0
-* **]1.0,2.0]** matches all versions greater than 1.0 and lower or equal to 2.0
-* **]1.0,2.0[** matches all versions greater than 1.0 and lower than 2.0
-* **[1.0,)** matches all versions greater or equal to 1.0
-* **]1.0,)** matches all versions greater than 1.0
-* **(,2.0]** matches all versions lower or equal to 2.0
-* **(,2.0[** matches all versions lower than 2.0
+* @[1.0,2.0]@ matches all versions greater or equal to 1.0 and lower or equal to 2.0
+* @[1.0,2.0[@ matches all versions greater or equal to 1.0 and lower than 2.0
+* @]1.0,2.0]@ matches all versions greater than 1.0 and lower or equal to 2.0
+* @]1.0,2.0[@ matches all versions greater than 1.0 and lower than 2.0
+* @[1.0,)@ matches all versions greater or equal to 1.0
+* @]1.0,)@ matches all versions greater than 1.0
+* @(,2.0]@ matches all versions lower or equal to 2.0
+* @(,2.0[@ matches all versions lower than 2.0
 
 h2. <a name="yml">dependencies.yml</a>
 

documentation/manual/evolutions.textile

@@ -2,9 +2,9 @@ h1. Managing database evolutions
 
 When you use a relational database, you need a way to track and organize your database schema evolutions. Typically there are several situation where you need a more sophisticated way to track your database schema changes:
 
-* When you work within a team of developer, each person need to know about any schema change.
+* When you work within a team of developers, each person needs to know about any schema change.
 * When you deploy on a production server, you need to have a robust way to upgrade your database schema.
-* If you work on several machines, you need to keep all database schema synchronized.
+* If you work on several machines, you need to keep all database schemas synchronized.
 
 p(note). If you work with JPA, Hibernate can handle database evolutions for you automatically. Evolutions are useful if you don't use JPA or if you prefer to manually take care of your database schema for finer tuning. 
 
@@ -40,7 +40,7 @@ DROP TABLE User;
 
 As you see you have to delimitate the both *Ups* and *Downs* section by using comments in your SQL script.
 
-When **evolutions** are activated, Play will check your database schema state before each request in DEV mode, or before starting the application in PROD mode. In DEV mode, if you database schema is not up to date, an error page will propose you to synchronize you database schema by running the appropriate SQL script.
+When **evolutions** are activated, Play will check your database schema state before each request in DEV mode, or before starting the application in PROD mode. In DEV mode, if your database schema is not up to date, an error page will suggest that you to synchronize your database schema by running the appropriate SQL script.
 
 !images/evolutions!
 
@@ -68,7 +68,7 @@ CREATE TABLE Post (
 # --- !Downs
 DROP TABLE Post;
 
-And Play apply it to his database.
+Play will apply this evolution script to Developer A’s database.
 
 On the other hand, developer B will work on a feature that require to alter the User table. So it will also create the following **2.sql** evolution script:
 
@@ -138,13 +138,13 @@ DROP TABLE Post;
 
 This evolution script represents the new **revision 2** of the database, that is different of the previous revision 2 that developer A has already applied. 
 
-So Play will detect it and ask developer A to synchronize its database by first reverting the old revision 2 already applied, and by applying the new revision 2 script:
+So Play will detect it and ask developer A to synchronize his database by first reverting the old revision 2 already applied, and by applying the new revision 2 script:
 
 !images/evolutions-conflict!
 
 h2. Inconsistent states
 
-Sometimes you will make some mistake in your evolution scripts, and they will fail. In this case, Play will mark your database schema in an inconsistent state and will ask you to manually resolve the problem before continuing.
+Sometimes you will make a mistake in your evolution scripts, and they will fail. In this case, Play will mark your database schema as being in an inconsistent state and will ask you to manually resolve the problem before continuing.
 
 For example, the **Ups** script of this evolution has an error:
 
@@ -164,7 +164,7 @@ Now before continuing you have to fix this inconsistency. So you run the fixed S
 
 bc. ALTER TABLE User ADD company varchar(255);
 
-And then mark this problem as manually resolved by clicking on the button.
+… and then mark this problem as manually resolved by clicking on the button.
 
 But because you evolution script has error, you probably want to fix it. So you modify the **3.sql** script:
 
@@ -176,7 +176,7 @@ ALTER TABLE User ADD company varchar(255);
 # --- !Downs
 ALTER TABLE User DROP company;
 
-Play detects this new evolution that replace the previous *3* one, and will run the following script:
+Play detects this new evolution that replaces the previous *3* one, and will run the following script:
 
 !images/evolutions-resolve!
 
@@ -281,15 +281,15 @@ ALTER TABLE User ADD company varchar(255);
 ~ or apply it yourself and mark it done using `play evolutions:markApplied`
 ~
 
-If you want that Play automatically run this evolution for you, then run:
+If you want Play to automatically run this evolution for you, then run:
 
 bc. $ play evolutions:apply
 
-If you prefer running this script manually on your production database, you need to tell Play that you database is up to date by running:
+If you prefer running this script manually on your production database, you need to tell Play that you database is up-to-date by running:
 
 bc. $ play evolutions:markApplied
 
-If there are any error while automatically running the evolutions scripts, as in DEV mode, you need to manually resolve them, and mark your database schema a fixed by running:
+If there are any errors while automatically running the evolutions scripts, as in DEV mode, you need to manually resolve them, and mark your database schema a fixed by running:
 
 bc. $ play evolutions:resolve
 

documentation/manual/home.textile

@@ -1,6 +1,6 @@
 h1. Documentation
 
-Welcome to the play framework documentation. This documentation is intended for the *1.2 release* and may significantly differs from previous versions of the framework. 
+Welcome to the Play framework documentation. This documentation is intended for the *1.2 release* and may significantly differ from previous framework versions’ documentation. 
 
 Check the "version 1.2 release notes":releasenotes-1.2.
 
@@ -87,7 +87,7 @@ Everything you need to know about Play.
 ## "Explicit save":jpa#save
 ## "More about generic typing problems":jpa#typing
 # "Play libs":libs
-## "Parsing XML using XPath":libs#ParsingXMLusingXPath
+## "XML parsing using XPath":libs#ParsingXMLusingXPath
 ## "Web Service client":libs#WebServiceclient
 ## "Functional programming with Java":libs#FunctionalprogrammingwithJava
 ## "OAuth":libs#OAuth
@@ -101,7 +101,7 @@ Everything you need to know about Play.
 ## "HTTP response streaming":asynchronous#HTTPresponsestreaming
 ## "Using WebSockets":asynchronous#UsingWebSockets
 # "Ajax requests":ajax
-## "Making ajax requests with JQuery":ajax#jsaction
+## "Making Ajax requests with JQuery":ajax#jsaction
 # "Internationalization":i18n
 ## "Only use UTF-8":i18n#utf8
 ## "Externalize your messages":i18n#messages
@@ -136,7 +136,7 @@ Everything you need to know about Play.
 # "Dependency management":dependency
 ## "Dependency format":dependency#format
 ## "dependencies.yml":dependency#yml
-## "Conflicts resolution":dependency#conflicts
+## "Conflict resolution":dependency#conflicts
 ## "Adding new repositories":dependency#repositories
 # "Managing your database evolutions":evolutions
 ## "Evolutions scripts":evolutions#script
@@ -165,14 +165,14 @@ h2. <a name="references">References</a>
 Extended references for day-to-day hacking.
 
 # "Quick index":index
-# "Browse API documentation (Javadoc)":/@api/index.html
+# "API documentation (Javadoc)":/@api/index.html
 # "Cheat sheets":cheatsheet/commandLine
 ## "Command Line":cheatsheet/commandLine
 ## "Controllers":cheatsheet/controllers
 ## "Templates":cheatsheet/templates
 ## "Model":cheatsheet/model
 ## "Testing":cheatsheet/tests
-## "Multi Environment":cheatsheet/multiEnvironment
+## "Multi-environment":cheatsheet/multiEnvironment
 # "Built-in extensions":tags
 ## "Template tags":tags
 ## "Java extensions":javaextensions
@@ -189,7 +189,7 @@ h2. <a name="versionnotes">Version notes</a>
 
 New versions of Play include certain changes. Check older release notes for:
 
-# "Play 1.1":releasenotes-1.1 
-# "Play 1.0.3":releasenotes-1.0.3 
-# "Play 1.0.2":releasenotes-1.0.2 
+# "Play 1.1":releasenotes-1.1
+# "Play 1.0.3":releasenotes-1.0.3
+# "Play 1.0.2":releasenotes-1.0.2
 # "Play 1.0.1":releasenotes-1.0.1

documentation/manual/index.textile

@@ -2,7 +2,7 @@ h1. Index
 
 Use this page to navigate quickly to a specific Play framework function.
 
-h2. Implicits Template variables
+h2. Implicit template variables
 
 <div class="index">
 # "errors":/@api/play/data/validation/Validation.html#errors%28%29
@@ -16,27 +16,33 @@ h2. Implicits Template variables
 # "session":/@api/play/mvc/Scope.Session.html
 </div>
 
-h2. Built-in Tags
+h2. Built-in tags
 
 <div class="index">
 # "a":tags#a
-# "doLayout":tags#doLayout
+# "authenticityToken":tags#authenticityToken
+# "cache":tags#cache
+# "doLayout":tags#dolayout
 # "else":tags#else
 # "elseif":tags#elseif
+# "error":tags#error
+# "errorClass":tags#errorClass
 # "errors":tags#errors
-# "ifError":tags#ifError
-# "ifErrors":tags#ifErrors
 # "extends":tags#extends
 # "field":tags#field
 # "form":tags#form
 # "get":tags#get
 # "i18n":tags#i18n
 # "if":tags#if
+# "ifError":tags#iferror
+# "ifErrors":tags#iferrors
 # "ifnot":tags#ifnot
 # "include":tags#include
-# "jsAction":tags#jsAction
+# "jsAction":tags#jsaction
 # "list":tags#list
 # "option":tags#option
+# "script":tags#script
+# "render":tags#render
 # "select":tags#select
 # "set":tags#set
 # "stylesheet":tags#stylesheet

documentation/manual/libs.textile

@@ -2,18 +2,18 @@ h1. Play libs
 
 The @play.libs@ package contains several useful libraries that will help you to achieve common programming tasks. 
 
-Most of these libraries are simple helpers that are really straight forward to use: 
+Most of these libraries are simple helpers that are really straightforward to use: 
 
 * "Codec":/@api/play/libs/Codec.html: Utilities to encode and decode data.
 * "Crypto":/@api/play/libs/Crypto.html: Cryptographics utilities.
-* "Expression":/@api/play/libs/Expression.html: Evaluation dynamic expressions.
+* "Expression":/@api/play/libs/Expression.html: Evaluate dynamic expressions.
 * "F":/@api/play/libs/F.html: Functional programming with Java.
 * "Files":/@api/play/libs/Files.html: File system manipulation helpers.
 * "I18N":/@api/play/libs/I18N.html: Internationalization helpers.
 * "IO":/@api/play/libs/IO.html: Stream manipulation helpers.
-* "Images":/@api/play/libs/Images.html: Images manipulation utilities.
-* "Mail":/@api/play/libs/Mail.html: Email functions.
-* "MimeTypes":/@api/play/libs/MimeTypes.html: Dealing with mime-types.
+* "Images":/@api/play/libs/Images.html: Image manipulation utilities.
+* "Mail":/@api/play/libs/Mail.html: E-mail functions.
+* "MimeTypes":/@api/play/libs/MimeTypes.html: Dealing with MIME types.
 * "OAuth":/@api/play/libs/OAuth.html: OAuth client protocol.
 * "OAuth2":/@api/play/libs/OAuth2.html: OAuth2 client protocol.
 * "OpenID":/@api/play/libs/OpenID.html: OpenID client protocol.
@@ -22,11 +22,11 @@ Most of these libraries are simple helpers that are really straight forward to u
 * "XML":/@api/play/libs/XML.html: Loading XML structures.
 * "XPath":/@api/play/libs/XPath.html: Parsing XML using XPath.
 
-The following sections provide more informations about the most important libraries.
+The following sections provide more information about the most important libraries.
 
 h2. Parsing XML using XPath
 
-XPath is probably the easiest way to parse an XML document without having to use code generation tools. The @play.libs.XPath@ library offer all the needed primitive to efficiently achieve this task.
+"XPath":http://en.wikipedia.org/wiki/XPath is probably the easiest way to parse an XML document without having to use code generation tools. The @play.libs.XPath@ library offers all the needed primitives to efficiently achieve this task.
 
 The @XPath@ operations operate on all @org.w3.dom.Node@ types:
 
@@ -65,7 +65,7 @@ Document xml = res.getXml();
 JsonElement json = res.getJson();
 InputStream is = res.getStream();
 
-You can also use the *async* API to make HTTP requests in a non-blocking way. Then you will receive a @Promise<HttpResponse>@. Once redeem, you can use the @HttpResponse@ as usual:
+You can also use the *async* API to make HTTP requests in a non-blocking way. Then you will receive a @Promise<HttpResponse>@. Once redeemed, you can use the @HttpResponse@ as usual:
 
 bc. Promise<HttpResponse> futureResponse = WS.url(
     "http://www.google.com"
@@ -75,29 +75,29 @@ h2. Functional programming with Java
 
 The @play.libs.F@ library provide several useful constructs coming from functional programming. These constructs are used to handle complex abstraction cases. For those that are accustomed to functional programming we provide:
 
-* Option<T> (a T value that can be or not set)
-* Either<A,B> (contains either a A value or a B value)
-* Tuple<A,B> (contains both A and B values)
+* @Option<T>@ (a T value that can be or not set)
+* @Either<A,B>@ (contains either a A value or a B value)
+* @Tuple<A,B>@ (contains both A and B values)
 
 h3. Promises
 
-@Promise@ is the Play's custom @Future@ type. In fact a @Promise<T>@ is also a @Future<T>@ so you can use it as a standard @Future@. But it has also a very interesting property: the ability to register callback using @onRedeem(…)@ that will be called as soon as the promised value is available. 
+A @Promise@ is Play’s custom @Future@ type. In fact a @Promise<T>@ is also a @Future<T>@ so you can use it as a standard @Future@. But it has also a very interesting property: the ability to register callback using @onRedeem(…)@ that will be called as soon as the promised value is available. 
 
 Promises are used everywhere in Play in place of Future (for Jobs, WS.async, etc…).
 
-Promises can be combined in several way. For example:
+Promises can be combined in several ways. For example:
 
 bc. Promise p = Promise.waitAll(p1, p2, p3)
 Promise p = Promise.waitAny(p1, p2, p3)
 Promise p = Promise.waitEither(p1, p2, p3)
 
 h3. Pattern Matching
 
-Sometimes we feel that we needed pattern matching in Java. Unfortunately Java has not built-in pattern matching, and because of the lack of function, it is difficult to add it as a library. Anyway we've worked on a solution that is not so bad.
+Sometimes we feel that we need pattern matching in Java. Unfortunately Java does not have built-in pattern matching, and because of the lack of functional constructs, it is difficult to add it as a library. Anyway we’ve worked on a solution that is not so bad.
 
-Our idea was to use the latest 'for loop' syntax to achieve basic pattern matching for Java. Pattern matching must both check if your object matches the required conditions and extract the interesting value. The Pattern matching library for Play is part of the @play.libs.F@ library.
+Our idea was to use the latest ‘for loop’ syntax to achieve basic pattern matching for Java. Pattern matching must both check if your object matches the required conditions and extract the interesting value. The Pattern matching library for Play is part of the @play.libs.F@ library.
 
-Let's see a simple example; you have a reference of type Object and you want to check that it is a string that starts by "command:". 
+Let’s see a simple example; you have a reference of type Object and you want to check that it is a string that starts by "command:". 
 
 The standard way would be:
 
@@ -114,20 +114,21 @@ bc. for(String s: String.and(StartsWith("command:")).match(o)) {
     System.out.println(s.toUpperCase());
 }
 
-The for loop is executed once, only if the condition is met, and it automatically extracts the String value without the need of casting. Because there is no explicit cast, all this thing is type safe, and checked by the compiler.
+The for loop is executed once, only if the condition is met, and it automatically extracts the String value without the need for casting. Because there is no explicit cast, everything is type-safe, and checked by the compiler.
 
 h2. OAuth
 
-"OAuth":http://oauth.net/ is an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.
+"OAuth":http://oauth.net/ is an open protocol for secure API authorization, using a simple and standard approach, from desktop and web applications.
 
 Two different specifications exist: OAuth 1.0 and OAuth 2.0. Play provides libraries to connect as a consumer to services proposing either of these specifications.
 
 The general process is the following:
-* Redirect the user to the authorization page of the provider
+
+* Redirect the user to the provider’s authorization page
 * After the user grants authorization, he is redirected back to your server along with an unauthorized token
-* Your server exchanges the unauthorized token with an access token specific to the current user, that needs to be saved in order to perform requests to the service. This step is done as a server-to-server communication.
+* Your server exchanges the unauthorized token with an access token specific to the current user, that needs to be saved in order to perform requests to the service. This step is done as server-to-server communication.
 
-The Play framework will take care of most of the process.
+The Play framework takes care of most of the process.
 
 h3. <a>OAuth 1.0</a>
 
@@ -165,14 +166,15 @@ bc. public static void authenticate() {
     redirect(twitt.redirectUrl(tokens));
 }
 
-Then, call can be done by signing the requests using the token pair:
+Calls can now be done by signing the requests using the token pair:
+
 bc. mentions = WS.url(url).oauth(TWITTER, getUser().getTokenPair()).get().getString();
 
 The full example usage is available in **samples-and-tests/twitter-oauth**.
 
 h3. <a>OAuth 2.0</a>
 
-OAuth 2.0 is much simpler that OAuth 1.0 because it doesn't involve signing requests. It is used by "Facebook":http://developers.facebook.com/docs/authentication/ and "37signals":http://37signals.com
+OAuth 2.0 is much simpler than OAuth 1.0 because it doesn’t involve signing requests. It is used by "Facebook":http://developers.facebook.com/docs/authentication/ and "37signals":http://37signals.com.
 
 Functionality is provided by **play.libs.OAuth2**.