Adding links and <?php tags so code is highlighted.

en/appendices.rst

@@ -2,7 +2,7 @@ Appendices
 ##########
 
 Appendices contain information regarding the new features
-introduced in 1.3, migration path from 1.2 to 1.3 and 2.0 migration guide.
+introduced in 2.0, and the migration path from 1.3 to 2.0.
 
 2.0 Migration Guide
 =========================

en/appendices/2-0-migration-guide.rst

@@ -33,15 +33,12 @@ Internationalization / Localization
 __() (Double underscore shortcut function) always returns the translation
 (not echo anymore).
 
-If you want to echo the result of the translation, use:
-
-::
+If you want to echo the result of the translation, use::
 
+    <?php
     echo __('My Message');
     
-This change includes all shortcut translation methods:
-
-::
+This change includes all shortcut translation methods::
 
     __()
     __n()
@@ -53,10 +50,9 @@ This change includes all shortcut translation methods:
 
 Alongside this, if you pass additional parameters, the translation will call
 `sprintf <http://php.net/manual/en/function.sprintf.php>`_  with these
-parameters before returning. For example:
-
-::
+parameters before returning. For example::
 
+    <?php
     // Will return something like "Called: MyClass:myMethod"
     echo __('Called: %s:%s', $className, $methodName);
 
@@ -104,8 +100,17 @@ Basics.php
 -  Global var called ``$TIME_START`` was removed use
    ``$_SERVER['REQUEST_TIME']`` instead.
 
+Removed Constants
+-----------------
+
+A number of constants were removed, as they were no longer accurate, or
+duplicated.
+
+- CONTROLLERS
+- ... more needed ...
+
 CakeRequest
------------
+===========
 
 This new class encapsulates the parameters and functions related to an incoming
 request. It replaces many features inside ``Dispatcher``,
@@ -115,7 +120,7 @@ request. It replaces many features inside ``Dispatcher``,
 change. See the CakeRequest new features for more information.
 
 Request handling, $_GET['url'] and .htaccess files
---------------------------------------------------
+==================================================
 
 CakePHP no longer uses ``$_GET['url']`` for handling application request paths.
 Instead it uses ``$_SERVER['PATH_INFO']``. This provides a more uniform way of
@@ -190,12 +195,14 @@ AuthComponent
 
 The AuthComponent was entirely re-factored for 2.0, this was done to help reduce
 developer confusion and frustration. In addition, AuthComponent was made more
-flexible and extensible. You can find out more in the AuthComponent guide.
+flexible and extensible. You can find out more in 
+the :doc:`/core-libraries/core-components/authentication` guide.
 
 EmailComponent
+--------------
 
 The EmailComponent has been deprecated and has created a new library class to
-send e-mails. See Email changes for more details.
+send e-mails. See :doc:`/core-utility-libraries/email` Email changes for more details.
 
 cakeError removed
 =================
@@ -211,7 +218,7 @@ Error handling
 The error handling implementation has dramatically changed in 2.0. Exceptions
 have been introduced throughout the framework, and error handling has been
 updated to offer more control and flexibility. You can read more in the
-exceptions and error handling section.
+:doc:`/development/exceptions` and :doc:`/development/errors` section.
 
 Lib classes
 ===========
@@ -228,13 +235,13 @@ App
 CakeLog
 -------
 
--  Log streams now need to implement CakeLogInterface. Exceptions will be raised
+-  Log streams now need to implement :php:class:`CakeLogInterface`. Exceptions will be raised
    if a configured logger does not.
 
 Cache
 -----
 
--  Cache is now a static class, it no longer has a getInstance() method.
+-  :php:class:`Cache` is now a static class, it no longer has a getInstance() method.
 -  CacheEngine is now an abstract class. You cannot directly create instances of 
    it anymore.
 -  CacheEngine implementations must extend CacheEngine, exceptions will be
@@ -248,6 +255,7 @@ Cache
 
 ::
 
+    <?php
     Cache::config('something');
     Cache::write('key, $value);
     
@@ -285,10 +293,10 @@ Configure
 -  ``Configure::read()`` with no parameter no longer returns the value of
    'debug' instead it returns all values in Configure. Use
    ``Configure::read('debug');`` if you want the value of debug.
--  ``Configure::load()`` now requires a ConfigReader to be setup. Read Configure
-   updates for more information.
+-  ``Configure::load()`` now requires a ConfigReader to be setup. Read 
+   :ref:`loading-configuration-files` for more information.
 -  ``Configure::store()`` now writes values to a given Cache configuration. Read
-   Configure updates for more information.
+   :ref:`loading-configuration-files` for more information.
 
 Scaffold
 --------
@@ -330,7 +338,7 @@ Xml
 -  ``Xml::toArray()``: static method that returns an array from
    SimpleXMLElement.
 
-You should see the Xml features page for more information on the changes made to
+You should see the :php:class:`Xml` documentation for more information on the changes made to
 the Xml class.
 
 Inflector
@@ -362,9 +370,6 @@ version 1.3.
 
 They are replaced with the JsHelper and HtmlHelper.
 
-Further documentation can be found in the
-:doc:`migrating-from-cakephp-1-2-to-1-3`.
-
 JsHelper
 --------
 
@@ -518,25 +523,22 @@ Models
 ======
 
 As now models relationships are lazy loaded. You can run into situation when
-assigning a value to an inexistent model property will throw errors
-
-::
+assigning a value to an inexistent model property will throw errors::
 
+    <?php
     $Post->inexistentProperty[] = 'value';
 
 will throw the error "Notice: Indirect modification of overloaded property
 $inexistentProperty has no effect". Assigning an initial value to the property
-solves the issue:
-
-::
+solves the issue::
 
+    <?php
     $Post->inexistentProperty = array();
     $Post->inexistentProperty[] = 'value';
 
-Or just declare the property in the model class:
-
-::
+Or just declare the property in the model class::
 
+    <?php
     class Post {
         var $inexistantPropert = array();
     }
@@ -563,17 +565,13 @@ Plugins
 
 Plugins no longer magically append their plugin prefix to components, helpers
 and models used within them. You must be explicit with the components, models,
-and helpers you wish to use. In the past:
-
-::
+and helpers you wish to use. In the past::
 
     var $components = array('Session', 'Comments');
 
 Would look in the controller's plugin before checking app/core components, it
 will now only look in the app/core components. If you wish to use objects from a
-plugin you must put the plugin name.
-
-::
+plugin you must put the plugin name::
 
     var $components = array('Session', 'Comment.Comments');
 
@@ -655,10 +653,9 @@ When defining database connections you will need to made some changes to the way
 configs were defined in the past. Basically in the database configuration class,
 the key "driver" is not accepted anymore, only "datasource", in order to make it
 more consistent. Also, as the datasources have been moved to packages you will
-need to pass the package they are located in. Example:
-
-::
+need to pass the package they are located in. Example::
 
+    <?php
     public $default = array(
         'datasource' => 'Database/Mysql',
         'persistent' => false,

en/core-utility-libraries/email.rst

@@ -7,31 +7,30 @@ CakeEmail
 class you can send email from any place of your application, ie. Controllers,
 Models, Console.
 
-This class replace the ``EmailComponent`` and give more flexibility to you send
-your emails. For example, you can create your custom methods to send email
-instead use the hard-coded smtp and mail.
+This class replace the :php:class:`EmailComponent` and give more flexibility to
+you send your emails. For example, you can create your custom methods to send
+email instead use the hard-coded smtp and mail.
 
 Basic usage
 ===========
 
-First of all, you should call the ``App::uses()`` to import the class:
+First of all, you should call the :php:meth:`App::uses()` to import the class:
 ``App::uses('CakeEmail', 'Network/Email');``.
 
 The use of the class is similar of ``EmailComponent``, but instead use
-attributes you must use methods. Example:
-::
+attributes you must use methods. Example::
 
+    <?php
     $email = new CakeEmail();
     $email->from('me@example.com');
     $email->to('you@example.com');
     $email->subject('About');
     $email->send('My message');
 
 To simplify, all set methods return the instance of class. You can re-write the
-same code as:
-
-::
+same code as::
 
+    <?php
     $email = new CakeEmail();
     $email->from('me@example.com')->to('you@example.com')->subject('About')->send('My message');
 
@@ -48,27 +47,38 @@ templates are now located in ``app/View/Emails/html/template.ctp`` and
 **Headers**
 
 In ``EmailComponent`` you only can set the ``X-*`` headers. In ``CakeEmail`` you
-are free to set what you want. So, if you are migrating to the new class, do not
+are free to set the headers you want. When migrating to use CakeEmail, do not
 forget to put the ``X-`` prefix in your headers.
 
 **Sender configuration**
 
-Now you can configure the sender header easily using the ``sender()`` method.
+Now you can configure the sender header easily using the 
+:php:meth:`~CakeEmail::sender()` method.
 
 **Attachments**
 
-The attachment format has changed. Below the new forms:
+The attachment format has changed. Below are the new forms:
 
 1. String: ``$email->attachments('/full/file/path/file.png')`` will attach this
    file with the name file.png.
 2. Array: ``$email->attachments(array('/full/file/path/file.png')`` will have
-   the same behavior of string.
+   the same behavior as using a string.
 3. Array with key:
    ``$email->attachments(array('photo.png' => '/full/some_hash.png'))`` will
-   attach some_hash.png with the name photo.png.
-4. Array with arrays:
-   ``$email->attachments(array('photo.png' => array('file' =>'/full/some_hash.png', 'mimetype' => 'image/png', 'contentId' => 'my-unique-id')))``
-   will attach the file with different mimetype and with custom Content ID
+   attach some_hash.png with the name photo.png. The recipient will see
+   photo.png, not some_hash.png.
+4. Array with arrays::
+   
+        <?php
+        $email->attachments(array(
+            'photo.png' => array(
+                'file' => '/full/some_hash.png',
+                'mimetype' => 'image/png',
+                'contentId' => 'my-unique-id'
+            )
+        ));
+
+   The above will attach the file with different mimetype and with custom Content ID
    (when set the content ID the attachment is transformed to inline). The
    mimetype and contentId are optional in this form.
 
@@ -80,16 +90,16 @@ The attachment format has changed. Below the new forms:
 Transports are classes designed to send the e-mail over some protocol or method.
 CakePHP support the Mail (default) and Smtp transports.
 
-To configure your method, you must use the ``CakeEmail::transport()`` method.
+To configure your method, you must use the :php:meth:`CakeEmail::transport()` method.
 
 **Creating custom Transports**
 
 You are able to create your custom transports to integrate with others emails
 systems (like SwiftMailer). To it, you must to create the file
-``app/Network/Email/YourTransport.php`` (where Your is the name of your
+``app/Network/Email/ExampleTransport.php`` (where Example is the name of your
 transport).
 
-This file must contain the class ``YourTransport`` extending
+This file must contain the class ``ExampleTransport`` extending
 ``AbstractTransport`` (do not forget to use
 ``App::uses('AbstractTransport', 'Network/Email');`` before).
 
@@ -99,11 +109,10 @@ before the send to pass the user configurations. By default, this method put the
 configuration in protected attribute ``$_config``.
 
 If you need to call some method from this transport before send, you can call
-the method ``transportClass()`` from ``CakeEmail`` to get an instance of
-transport. Example:
-
-::
+:php:meth:`CakeEmail::transportClass()` to get an instance of
+transport. Example::
 
+    <?php
     $yourInstance = $email->transport('your')->transportClass();
     $yourInstance->myCustomMethod();
     $email->send();
@@ -123,9 +132,7 @@ that.
 
 You also can configure SMTP servers with SSL connection, like GMail. To it, put
 ``'ssl://'`` at prefix in the host and configure properly the port value.
-Example:
-
-::
+Example::
 
     public $gmail = array(
         'host' => 'ssl://smtp.gmail.com',
@@ -141,22 +148,22 @@ Example:
 
 **Deliver**
 
-Are you bored with too many configurations to do every time? You send every time
-the same email? Ok, now it is more easy...
+Sometimes you need a quick way to fire off an email, and you don't necessarily
+want do setup a bunch of configuration ahead of time. 
+:php:meth:`~CakeEmail::deliver()` is intended for that purpose.
 
 You can create a configuration in ``EmailConfig`` or an array with all options
-that you need and use the static method ``CakeEmail::deliver()``. Example:
-
-::
+that you need and use the static method ``CakeEmail::deliver()``. Example::
 
+    <?php
     CakeEmail::deliver('you@example.com', 'Subject', 'Message', array('from' => 'me@example.com'));
 
 This method will send an email to you@example.com, from me@example.com with
 subject Subject and content Message.
 
-The return is a ``CakeEmail`` instance with all configurations setted. If you do
-not want send the email and configure something more before send, you can pass
-the 5th parameter as false.
+The return is a :php:class:`CakeEmail` instance with all configurations setted.
+If you do not want send the email and configure something more before send, you
+can pass the 5th parameter as false.
 
 The 3rd parameter is the content of message or an array with variables (when
 using rendered content).
@@ -190,5 +197,11 @@ follow configurations are used:
 
 All these configurations are optional, except ``'from'``. If you put more
 configurations in this array, these configurations will be used in the
-``CakeEmail::config()`` method. For example, if you are using smtp transport,
+:php:meth:`CakeEmail::config()` method. For example, if you are using smtp transport,
 you should pass the host, port and others configurations.
+
+.. todo::
+
+    More information on the various method CakeEmail provides
+    and how to use them all.  There is a good start here, but
+    more detail would be good.