[playframework#633] Docs: link to new configuration reference

documentation/manual/cache.textile

@@ -96,16 +96,7 @@ Here we have used a unique UUID to keep unique information in the Cache for each
 
 h2. <a name="memcached">Configure memcached</a>
 
-When you want to enable a real Memcached implementation, enable Memcached and define the daemon address in your @application.conf@:
-
-bc. memcached=enabled
-memcached.host=127.0.0.1:11211
-
-You can connect to a distributed cache by specifying multiple daemon addresses: 
-
-bc. memcached=enabled
-memcached.1.host=127.0.0.1:11211
-memcached.2.host=127.0.0.1:11212
+When you want to enable a real Memcached implementation, enable Memcached  with the "memcached configuration":configuration#memcached and define the daemon address in the "memcached.host configuration":configuration#memcached.host.
 
 p(note). **Continuing the discussion**
 

documentation/manual/configuration.textile

@@ -175,7 +175,7 @@ h2(#attachments). Attachments
 
 h3(#attachments.path). attachments.path
 
-Storage path for @play.db.jpa.Blob@ content. For example:
+Storage path for @play.db.jpa.Blob@ content. This can be an absolute path, or a relative path to a folder inside the Play application folder. For example:
 
 bc. attachments.path=data/attachments
 
@@ -228,6 +228,8 @@ Sets the default date format, using a @java.text.SimpleDateFormat@ pattern. For
 
 bc. date.format=dd-MM-yyyy
 
+This property also affects how @${date.format()}@ renders dates in templates. It also set the default date format when binding a date parameter.
+
 Default: @yyyy-MM-dd@
 
 You can also set a different date format for specific languages that you have configured with "application.langs":#application.langs, for example:
@@ -604,7 +606,7 @@ bc. memcached.1.host=127.0.0.1:11211
 memcached.2.host=127.0.0.1:11212
 
 
-h2(#mimetype). Custom mime types
+h2(#mimetype). Custom MIME types
 
 You can declare additional MIME types. For example:
 
@@ -633,7 +635,7 @@ h2(#mail). Mail
 
 h3(#mail.debug). mail.debug
 
-Enables SMTP transaction logging.
+Enables SMTP transaction logging; under the hood, Play uses JavaMail to perform the actual SMTP transactions.
 
 bc. mail.debug=true
 
@@ -658,7 +660,7 @@ Default: none.
 
 h3(#mail.smtp.channel). mail.smtp.channel
 
-SMTP encrypted channel configuration, used with "mail.smtp.host":#mail.smtp.host. Values:
+There are two ways to send the e-mail over an encrypted channel, which you can choose with this configuration property. Values:
 
 * @clear@ - no encryption
 * @ssl@ - SMTP-over-SSL (SMTPS) connector; an SSL socket listening on port 465

documentation/manual/controllers.textile

@@ -170,17 +170,7 @@ bc.  public static void articlesSince(@As(lang={"fr,de","*"},
 
 In this example, we specified that for the French and German languages the date format is @dd-MM-yyyy@ and for all the other languages it's @MM-dd-yyyy@. Please note that the lang value can be comma separated. The important thing is that the number of parameters for lang matches the number of parameters for value. 
 
-If no <code>@As</code> annotation is specified, then Play! uses the default date format according to your locale.
-To set the default date format to use, edit your application.conf and set the following property:
-
-bc. date.format=yyy-MM-dd
-date.format.fr=dd/MM/yyyy
-
-Please note that the language fr in the application.conf must be enabled as well:
-
-bc. application.langs=fr
-
-This property also affects how the dates are rendered in the templates using @${date.format()}@.
+If no <code>@As</code> annotation is specified, then Play! uses the default date format according to your locale. The "date.format configuration":configuration#date.format specifies the default date format to use.
 
 
 h3. <a name="calendar">Calendar</a>
@@ -206,9 +196,7 @@ bc. String mimeType = MimeTypes.getContentType(attachment.getName());
 
 The @play.libs.MimeTypes@ class looks up the MIME type for the given file name’s extension in the file @$PLAY_HOME/framework/src/play/libs/mime-types.properties@ 
 
-You can also add your own types to your application’s @conf/application.conf@ file. For example, to add a MIME type for GIMP images with the @.xcf@ extension, add the line: 
-
-bc. mimetype.xcf=application/x-gimp-image 
+You can also add your own types using the "Custom MIME types configuration":configuration#mimetype.
 
 
 h3. <a name="array">Arrays or collections of supported types</a>
@@ -559,11 +547,8 @@ bc. <form action="@{application.index}" method="POST" accept-charset="ISO-8859-1
 
 h4. Custom encoding for the entire application
 
-Set the @application.web_encoding@ in @application.conf@ to specify which encoding Play uses when communicating with the browser. This also changes the default encoding for Play’s powerful "Web Service client":libs#WebServiceclient.
-
-bc. application.web_encoding=ISO-8859-1
+Configure "application.web_encoding":configuration#application.web_encoding to specify which encoding Play uses when communicating with the browser.
 
-Changing @application.web_encoding@ affects the @charset@ part of the @Content-type@ HTTP header. It also affects which encoding is used when transmitting rendered dynamic results, but it **does not** affect the bytes sent when Play serves static content: So, if you have modified the default response encoding and you have static text-files (in the @public/@ folder) that contain special characters, you must make sure that these files are stored according to the specified encoding. All other files should be stored in UTF-8.
 
 h2. <a name="interceptions">Interceptions</a>
 
@@ -773,11 +758,9 @@ bc. public static void index() {
     render(messages);
 }
 
-The session expires when you close your web browser, unless the @application.session.maxAge@ configuration property is set. For example:
-
-bc. application.session.maxAge=7d  # Remember for one week.
+The session expires when you close your web browser, unless you configure "application.session.maxAge":configuration#application.session.maxAge.
 
-The cache has different semantics than the classic Servlet HTTP session object. You can’t assume that these objects will be always in the cache. So it forces you to handle the cache miss cases, and keeps your application fully stateless.
+The cache has different semantics to the classic Servlet HTTP session object. You can’t assume that these objects will be always in the cache. So it forces you to handle the cache miss cases, and keeps your application fully stateless.
 
 p(note). **Continuing the discussion**
 

documentation/manual/deployment.textile

@@ -53,16 +53,18 @@ bc.
 
 Replace com.example:archive=unique-archive-name with whatever you wish as long as it is unique.            
 
+
 h3. Datasource
 
-Play also supports Datasource and resource look-up. To use a JNDI Datasource, configure the Play database plugin (@play.db.DBPlugin@) in application.conf as shown below:
+Play also supports Datasource and resource look-up. To use a JNDI Datasource, set the "database configuration":configuration#dbconf as shown below:
 
 bc. db=java:comp/env/jdbc/mydb
 jpa.dialect=org.hibernate.dialect.Oracle10gDialect
 jpa.ddl=verify
 
 The database plugin detects the pattern @db=java:@ and will de-activate the default JDBC system.
 
+
 h3. Custom web.xml
 
 Some application servers, such as IBM Websphere, require you to declare a datasource in a @resource-ref@ element in the Servlet API’s @web.xml@ configuration file. By default, @web.xml@ is a file that is generated by Play when you execute the @play war@ command. To customise the generated @web.xml@, generate the exploded WAR version, then copy the generated @web.xml@ file to the @war/WEB-INF@ folder in your application. The next time you will execute the @play war@ command, it will copy your custom @web.xml@ from to the generated folder.

documentation/manual/emails.textile

@@ -112,48 +112,28 @@ Your can include links to your application in e-mails like this:
 
 bc. @@{application.index}
 
-If you send mails from Jobs you have to configure @application.baseUrl@ in @application.conf@. @application.baseUrl@ must be a valid external base URL to your application.
+If you send mails from Jobs you have to set "application.baseUrl":configuration#application.baseUrl to a valid external base URL for your application.
 
 For example, to send an e-mail from a Job running on the playframework.org web site, the configuration would look like this:
 
 bc. application.baseUrl=http://www.playframework.org/
 
 h2. <a name="smtp">SMTP configuration</a>
 
-E-mail functionality is configured in your application’s @conf/application.conf@ file. First of all, you need to define the SMTP server to use:
+E-mail functionality is configured by several "mail configuration":configuration#mail properties:
 
-bc. mail.smtp.host=smtp.taldius.net
+* SMTP server - "mail.smtp.host":configuration#mail.smtp.host
+* SMTP server authentication - "mail.smtp.user":configuration#mail.smtp.user and "mail.smtp.pass":configuration#mail.smtp.pass
+* encrypted channel - "mail.smtp.channel":configuration#mail.smtp.channel
+* JavaMail SMTP transaction logging - "mail.debug":configuration#mail.debug.
 
-If your SMTP server requires authentication, use the following properties: 
+Two additional configuration properties let you override default behaviour:
 
-bc. mail.smtp.user=jfp
-mail.smtp.pass=topsecret
+* "mail.smtp.socketFactory.class":configuration#mail.smtp.socketFactory.class
+* "mail.smtp.port":configuration#mail.smtp.port
 
-h3. Channel & ports
 
-There are two ways to send the e-mail over an encrypted channel. If your server supports the @starttls@ command (see: "RFC 2487":http://www.apps.ietf.org/rfc/rfc2487.html), you can use a clear connection on port 25 that will switch to SSL/TLS. You can do so by adding this configuration option:
-
-bc. mail.smtp.channel=starttls
-
-Your server may also provide a SMTP-over-SSL (SMTPS) connector, that is an SSL socket listening on port 465. In that case, you tell Play to use this setup using the configuration option:
-
-bc. mail.smtp.channel=ssl
-
-h2. <a name="configuration">More about configuration</a>
-
-Under the hood, Play uses JavaMail to perform the actual SMTP transactions. If you need to see what’s going on, try:
-
-bc. mail.debug=true
-
-When using SSL connections with JavaMail, the default SSL behavior is to drop the connection if the remote server certificate is not signed by a root certificate. This is the case in particular when using a self-signed certificate. Play’s default behavior is to skip that check. You can control this using the following property:
-
-bc. mail.smtp.socketFactory.class
-
-If you need to connect to servers using non-standard ports, the following property will override the defaults:
-
-bc. mail.smtp.port=2500
-
-h2. <a name="gmail">Using Gmail</a>
+h3. <a name="gmail">Using Gmail</a>
 
 To use Gmail’s servers, for example when you deploy with "playapps":http://www.playframework.org/modules/playapps, use this configuration: 
 

documentation/manual/evolutions.textile

@@ -40,8 +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.
 
-Evolutions are automatically activated if a database is configured in application.conf and evolution scripts are present. You can disable them by setting @evolutions.enabled=false@ in @application.conf@.
-For example when tests set up their own database you can disable evolutions for the test environment.
+Evolutions are automatically activated if a database is configured in @application.conf@ and evolution scripts are present. You can disable them by setting "evolutions.enabled":configuration#evolutions.enabled to @false@. For example when tests set up their own database you can disable evolutions for the test environment.
 
 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 synchronise your database schema by running the appropriate SQL script.
 

documentation/manual/i18n.textile

@@ -35,9 +35,7 @@ back=Retour
 
 h2. <a name="languages">Define languages supported by the application</a>
 
-In the @conf/application.conf@ file, define a list of supported languages:
-
-bc. application.langs=fr,en,ja
+Define a list of supported languages in the "application.langs configuration":configuration#application.langs.
 
 On the first request from a new user, Play will guess the default language to use. It does so by parsing the HTTP @Accept-language@ header. It will then save the chosen language in a @PLAY_LANG@ cookie. So the next request will use the same language.
 
@@ -55,19 +53,10 @@ bc. Lang.change("ja");
 
 The new value will be saved back to the user’s language cookie.
 
-h2. <a name="dates">Define date format according to your locale</a>
-
-To set the default date format to use, edit your application.conf and set the following property:
 
-bc. date.format=yyy-MM-dd
-date.format.fr=dd/MM/yyyy
-
-Please note that the language fr in the application.conf must be enabled as well (see above):
-
-bc. application.langs=fr,en
+h2. <a name="dates">Define date format according to your locale</a>
 
-This property affects how the dates are rendered in the templates using the ${date.format()}.
-It also set the default date format when binding a date parameter.
+Configure "date.format":configuration#date.format to specify the default date format to use.
 
 
 h2(#retrieve). <a>Retrieve localized messages</a>

documentation/manual/jpa.textile

@@ -200,9 +200,7 @@ If you upload another file for the same user, this will be saved as a new file o
 
 If the HTTP request did not specify the file’s correct MIME type, you can use file name extension mapping, as described in the "controller file upload":controllers#file section.
 
-To save attachments in a different folder, specify a different path in the @application.conf@ file. This can be an absolute path, or a relative path to a folder inside the Play application folder:
-
-bc. attachments.path=photos
+To save attachments in a different folder, configure "attachments.path":configuration#attachments.path.
 
 To serve a stored file, pass @Blob.get()@ to the controller’s @renderBinary@ method, as described in the "controller binary response":controllers#binary section.
 

documentation/manual/logs.textile

@@ -2,6 +2,7 @@ h1. Logging configuration
 
 The Play logger is built on "Log4j":http://logging.apache.org/log4j/1.2/index.html. Since most Java libraries use Log4j or a wrapper able to use Log4j as a backend, you can easily configure logging that is well-suited to your application.
 
+
 h2. <a name="logging">Logging from your application</a>
 
 Play provides a default logger with the class @play.Logger@. This class uses Log4j to write messages and exceptions to a logger named @play@.
@@ -20,13 +21,10 @@ You can still use Log4j directly to create alternative loggers for specific need
 
 bc. org.apache.log4j.Logger.getLogger("another.logger");
 
-h2. <a name="levels">Configure log levels</a>
-
-You can configure the Play logger’s log level. Just define this key in the @application.conf@ file:
 
-bc. application.log=INFO
+h2. <a name="levels">Configure log levels</a>
 
-You can change this value without restarting the server. Note that this level only applies to messages generated by the application.
+You can set the Play logger’s log level by configuring "application.log":configuration#application.log. You can change this value without restarting the server. Note that this level only applies to messages generated by the application.
 
 If you need to fully configure Log4j, create a @log4j.properties@ file in the @conf/@ directory. Since this directory is the first element of the classpath, this file will be the default used by all libraries.
 
@@ -43,6 +41,11 @@ log4j.appender.Console.layout.ConversionPattern=%d{ABSOLUTE} %-5p ~ %m%n
 
 Copy this file and update it for your specifics needs!
 
+
+h3. <a name="production">Production configuration</a>
+
+See: "configure logging for production":production#logging for another example.
+
 p(note). **Continuing the discussion**
 
 Next, we continue configuration with %(next)"Configuration in several environments":ids%.

documentation/manual/main.textile

@@ -82,7 +82,7 @@ The @conf@ directory contains all configuration files for the application.
 
 There are two required configuration files:
 
-* @application.conf@, the main configuration file for the application. It contains standard configuration options.
+* @application.conf@, the main configuration file for the application. It contains standard "configuration parameters":configuration.
 * @routes@, the routes definition file.
 
 If you need to add some configuration options specific to your application, it’s a good idea to add more options to the @application.conf@ file. Configuration options in this file are read programmatically with @Play.configuration.get("propertyName")@. When you create a new application, the @play new@ command copies a default configuration file from the @$PLAY_HOME/resources/application-skel/conf@ directory with some commented-out options to get you started.
@@ -112,7 +112,7 @@ There are no compilation, packaging or deployment phases while working with Play
 
 p(note). **About DEV/PROD modes**
 
-You can run an application either in a DEV or PROD mode. You toggle this mode using the *application.mode* configuration property. When run in DEV mode, Play will check for file changes and will handle hot reloading if necessary. 
+You can run an application either in a DEV or PROD mode. You toggle this mode using the "application.mode configuration":configuration#application.mode. When run in DEV mode, Play will check for file changes and will handle hot reloading if necessary. 
 
 The PROD mode is fully optimized for production: Java sources and templates are compiled once and cached for multiple uses.
 

documentation/manual/model.textile

@@ -146,32 +146,18 @@ h2. <a name="database">Set-up a database to persist your model objects</a>
 
 Most of the time you will need to save the model object data permanently. The most natural way is to save this data into a database. 
 
-During development, you can quickly set up an embedded database either in-memory or save it in a sub-directory within your application.
-
-To start an in-memory H2 database instance, just add this line to your @conf/application.conf@ file:
-
-bc. db=mem
-
-If your prefer to save the database in the file system, use:
-
-bc. db=fs
-
-If you want to connect to an existing **MySQL5 server**, use the following:
-
-bc. db=mysql:user:pwd@database_name
+During development, you can quickly set up an embedded database either in-memory or save it in a sub-directory within your application using the "db configuration":configuration#db.
 
 The Play distribution includes JDBC drivers for H2 and MySQL in the @$PLAY_HOME/framework/lib/@ directory. If you are using a PostgreSQL or Oracle database, for example, then you should add the JDBC driver library there, or in your application’s @lib/@ directory.
 
-To connect to any JDBC compliant database. Just add the driver library to and define JDBC properties in the application.conf:
+To connect to any JDBC compliant database. Just add the driver library to and define the JDBC properties "db.url":configuration#db.url, "db.driver":configuration#db.driver, "db.user":configuration#db.user and "db.pass":configuration#db.pass:
 
 bc. db.url=jdbc:mysql://localhost/test
 db.driver=com.mysql.jdbc.Driver
 db.user=root
 db.pass=
 
-You can also specify a JPA dialect with the configuration option:
-
-bc. jpa.dialect=<dialect>
+You can also configure a JPA dialect with "jpa.dialect":configuration#jpa.dialect.
 
 From your code, you can then obtain a @java.sql.Connection@ from the @play.db.DB@ and use it in the standard way.