restructuring guide index.md and structure

worked though all the guide files adjusted structure and
added some missing does

docs/guide/apps-own.md

@@ -0,0 +1,4 @@
+Creating your own Application structure
+=======================================
+
+TDB

docs/guide/basics.md

@@ -0,0 +1,83 @@
+Basic concepts of Yii
+=====================
+
+
+Component and Object
+--------------------
+
+Yii 2.0 breaks the `CComponent` class in 1.1 into two classes: `Object` and `Component`.
+The `Object` class is a lightweight base class that allows defining class properties
+via getters and setters. The `Component` class extends from `Object` and supports
+the event feature and the behavior feature.
+
+If your class does not need the event or behavior feature, you should consider using
+`Object` as the base class. This is usually the case for classes that represent basic
+data structures.
+
+
+Object Configuration
+--------------------
+
+The `Object` class introduces a uniform way of configuring objects. Any descendant class
+of `Object` should declare its constructor (if needed) in the following way so that
+it can be properly configured:
+
+```php
+class MyClass extends \yii\base\Object
+{
+    public function __construct($param1, $param2, $config = [])
+    {
+        // ... initialization before configuration is applied
+
+        parent::__construct($config);
+    }
+
+    public function init()
+    {
+        parent::init();
+
+        // ... initialization after configuration is applied
+    }
+}
+```
+
+In the above, the last parameter of the constructor must take a configuration array
+which contains name-value pairs for initializing the properties at the end of the constructor.
+You can override the `init()` method to do initialization work that should be done after
+the configuration is applied.
+
+By following this convention, you will be able to create and configure a new object
+using a configuration array like the following:
+
+```php
+$object = Yii::createObject([
+    'class' => 'MyClass',
+    'property1' => 'abc',
+    'property2' => 'cde',
+], $param1, $param2);
+```
+
+More on configuration in [configuration](configuration.md)
+
+
+Path Alias
+----------
+
+Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. An alias
+must start with a `@` character so that it can be differentiated from file/directory paths and URLs.
+For example, the alias `@yii` refers to the Yii installation directory. Path aliases are
+supported in most places in the Yii core code. For example, `FileCache::cachePath` can take
+both a path alias and a normal directory path.
+
+Path alias is also closely related with class namespaces. It is recommended that a path
+alias be defined for each root namespace so that you can use Yii the class autoloader without
+any further configuration. For example, because `@yii` refers to the Yii installation directory,
+a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library
+such as Zend Framework, you may define a path alias `@Zend` which refers to its installation
+directory and Yii will be able to autoload any class in this library.
+
+
+Autoloading
+-----------
+
+TBD

docs/guide/behaviors.md

@@ -0,0 +1,4 @@
+Behaviors
+=========
+
+TDB

docs/guide/composer.md

@@ -21,8 +21,8 @@ curl -s http://getcomposer.org/installer | php
 Adding more packages to your project
 ------------------------------------
 
-The act of [installing a Yii application](installing.md) creates the `composer.json` file in the root directory of your project.
+The act of [installing a Yii application](installation.md) creates the `composer.json` file in the root directory of your project.
-In this file you list the packages that your application requires. For Yii sites, the most important part of the file is `require` the section:
+In this file you list the packages that your application requires. For Yii sites, the most important part of the file is the `require` section:
 
 ```
 {
@@ -33,19 +33,23 @@ In this file you list the packages that your application requires. For Yii sites
 }
 ```
 
-Within the `require` section, you specify the name and version of each required package. The above example says that a version greater than or equal to 1.3 of Michaelf's PHP-Markdown package is required, as is version 4.5 or greater of Ezyang's HTMLPurifier. For details of this syntax, see the [official Composer documentation](http://getcomposer.org). 
+Within the `require` section, you specify the name and version of each required package.
+The above example says that a version greater than or equal to 1.3 of Michaelf's PHP-Markdown package is required,
+as is version 4.5 or greater of Ezyang's HTMLPurifier.
+For details of this syntax, see the [official Composer documentation](http://getcomposer.org).
 
-The full list of available Composer-supported PHP packages can be found at [packagist](http://packagist.org/). Any Yii extension can also be explicitly named using the syntax:
+The full list of available Composer-supported PHP packages can be found at [packagist](http://packagist.org/).
 
-???
+Once you have edited the `composer.json`, you can invoke Composer to install the identified dependencies.
-
+For the first installation of the dependencies, use this command:
-Once you have edited the `composer.json`, you can invoke Composer to install the identified dependencies. For the first installation of the dependencies, use this command:
 
 ```
 php composer.phar install
 ```
 
-This must be executed within your Yii project's directory, where the `composer.json` file can be found. Depending upon your operating system and setup, you may need to provide paths to the PHP executable and to the `composer.phar` script.
+This must be executed within your Yii project's directory, where the `composer.json` file can be found.
+Depending upon your operating system and setup, you may need to provide paths to the PHP executable and
+to the `composer.phar` script.
 
 For an existing installation, you can have Composer update the dependencies using:
 
@@ -55,7 +59,8 @@ php composer.phar update
 
 Again, you may need to provide specific path references.
 
-In both cases, after some waiting, the required packages will be installed and ready to use in your Yii application. No additional configuration of those packages will be required.
+In both cases, after some waiting, the required packages will be installed and ready to use in your Yii application.
+No additional configuration of those packages will be required.
 
 
 FAQ

docs/guide/configuration.md

@@ -1,10 +1,12 @@
 Configuration
 =============
 
-Yii applications rely upon components to perform most of the common tasks, such as connecting to a database, routing browser requests, and handling sessions. How these stock components behave can be adjusted by *configuring* your Yii application. The majority of components have sensible defaults, so it's unlikely that you'll spend a lot of time configuring
+Yii applications rely upon components to perform most of the common tasks, such as connecting to a database, routing browser
+requests, and handling sessions. How these stock components behave can be adjusted by *configuring* your Yii application.
+The majority of components have sensible defaults, so it's unlikely that you'll spend a lot of time configuring
 them. Still there are some mandatory settings, such as the database connection, that you will have to establish.
 
-How application is configured depends on application template but there are some general principles applying in any case.
+How an application is configured depends on application template but there are some general principles applying in any case.
 
 Configuring options in bootstrap file
 -------------------------------------
@@ -14,18 +16,18 @@ console applications it's `yii`. Both are doing nearly the same job:
 
 1. Setting common constants.
 2. Including Yii itself.
-3. Including Composer autoloader.
+3. Including [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading).
 4. Reading config file into `$config`.
 5. Creating new application instance using `$config` and running it.
 
-Bootstrap file is not the part of framework but your application so it's OK to adjust it to fit your application. Typical
+The Bootstrap file is not the part of framework but your application so it's OK to adjust it to fit your application. Typical
 adjustments are the value of `YII_DEBUG` that should never be `true` on production and the way config is read.
 
 Configuring application instance
 --------------------------------
 
 It was mentioned above that application is configured in bootstrap file when its instance is created. Config is typically
-stored in a PHP file in `/config` directory of the application and looks like the following:
+stored in a PHP file in the `/config` directory of the application and looks like the following:
 
 ```php
 <?php
@@ -33,18 +35,19 @@ return [
 	'id' => 'applicationId',
 	'basePath' => dirname(__DIR__),
 	'components' => [
-		// ...
+		// configuration of application components goes here...
 	],
 	'params' => require(__DIR__ . '/params.php'),
 ];
 ```
 
 In the above array keys are names of application properties. Depending on application type you can check properties of
-either `\yii\web\Application` or `\yii\console\Application`. Both are extended from `\yii\base\Application`.
+either [[yii\web\Application]] or [[yii\console\Application]]. Both are extended from [[yii\base\Application]].
 
 > Note that you can configure not only public class properties but anything accessible via setter. For example, to
   configure runtime path you can use key named `runtimePath`. There's no such property in the application class but
   since there's a corresponding setter named `setRuntimePath` it will be properly configured.
+  This feature is added to any class that extends from [[yii\base\Object]] which is nearly any class of the Yii framework.
 
 Configuring application components
 ----------------------------------
@@ -76,11 +79,11 @@ return [
 
 In the above four components are configured: `cache`, `user`, `errorHandler`, `log`. Each entry key is a component ID
 and the value is the configuration array. ID is used to access the component like `\Yii::$app->myComponent`.
-Configuration array has one special key named `class` that sets component class. The rest of the keys and values are used
+Configuration array has one special key named `class` that sets the component class. The rest of the keys and values are used
 to configure component properties in the same way as top-level keys are used to configure application properties.
 
-Each application has predefined set of the components. In case of configuring one of these `class` key is omitted and
+Each application has a predefined set of components. In case of configuring one of these, the `class` key is omitted and
-application default class is used instead. You can check `registerCoreComponents` method of the application you are using
+application default class is used instead. You can check `registerCoreComponents()` method of the application you are using
 to get a list of component IDs and corresponding classes.
 
 Note that Yii is smart enough to configure the component when it's actually used i.e. if `cache` is never used it will

docs/guide/console.md

@@ -0,0 +1,4 @@
+Building console applications
+=============================
+
+TDB

docs/guide/controller.md

@@ -177,12 +177,36 @@ public SiteController extends \yii\web\Controller
 
 After doing so you can access your action as `http://example.com/?r=site/about`.
 
-Filters
+
--------
+Action Filters
+--------------
+
+Action filters are implemented via behaviors. You should extend from `ActionFilter` to
+define a new filter. To use a filter, you should attach the filter class to the controller
+as a behavior. For example, to use the `AccessControl` filter, you should have the following
+code in a controller:
+
+```php
+public function behaviors()
+{
+    return [
+        'access' => [
+            'class' => 'yii\web\AccessControl',
+            'rules' => [
+                ['allow' => true, 'actions' => ['admin'], 'roles' => ['@']],
+            ),
+        ),
+    );
+}
+```
+
+more TDB
 
 Catching all incoming requests
 ------------------------------
 
+TDB
+
 See also
 --------
 

docs/guide/database-basics.md

@@ -5,6 +5,7 @@ Yii has a database access layer built on top of PHP's [PDO](http://www.php.net/m
 uniform API and solves some inconsistencies between different DBMS. By default Yii supports the following DBMS:
 
 - [MySQL](http://www.mysql.com/)
+- [MariaDB](https://mariadb.com/)
 - [SQLite](http://sqlite.org/)
 - [PostgreSQL](http://www.postgresql.org/)
 - [CUBRID](http://www.cubrid.org/) (version 9.1.0 and higher).

docs/guide/events.md

@@ -0,0 +1,42 @@
+Events
+======
+
+
+There is no longer the need to define an `on`-method in order to define an event in Yii 2.0.
+Instead, you can use whatever event names. To attach a handler to an event, you should
+use the `on` method now:
+
+```php
+$component->on($eventName, $handler);
+// To detach the handler, use:
+// $component->off($eventName, $handler);
+```
+
+
+When you attach a handler, you can now associate it with some parameters which can be later
+accessed via the event parameter by the handler:
+
+```php
+$component->on($eventName, $handler, $params);
+```
+
+
+Because of this change, you can now use "global" events. Simply trigger and attach handlers to
+an event of the application instance:
+
+```php
+Yii::$app->on($eventName, $handler);
+....
+// this will trigger the event and cause $handler to be invoked.
+Yii::$app->trigger($eventName);
+```
+
+If you need to handle all instances of a class instead of the object you can attach a handler like the following:
+
+```php
+Event::on(ActiveRecord::className(), ActiveRecord::EVENT_AFTER_INSERT, function ($event) {
+	Yii::trace(get_class($event->sender) . ' is inserted.');
+});
+```
+
+The code above defines a handler that will be triggered for every Active Record object's `EVENT_AFTER_INSERT` event.

docs/guide/extension.md

@@ -0,0 +1,4 @@
+Extending Yii
+=============
+
+TDB

docs/guide/form.md

@@ -1,7 +1,7 @@
 Working with forms
 ==================
 
-The primary way of using forms in Yii is through [[\yii\widgets\ActiveForm]]. This approach should be preferred when the form is based upon  a model. Additionally, there are some useful methods in [[\yii\helpers\Html]] that are typically used for adding buttons and help text to any form.
+The primary way of using forms in Yii is through [[yii\widgets\ActiveForm]]. This approach should be preferred when the form is based upon  a model. Additionally, there are some useful methods in [[\yii\helpers\Html]] that are typically used for adding buttons and help text to any form.
 
 When creating model-based forms, the first step is to define the model itself. The model can be either based upon the Active Record class, or the more generic Model class. For this login example, a generic model will be used:
 

docs/guide/gii.md

@@ -0,0 +1,25 @@
+The Gii code generation tool
+============================
+
+Yii2 includes a handy tool that allows rapid prototyping by generating commonly used code snippets
+as well as complete CRUD controllers.
+
+Installing and configuring
+--------------------------
+
+How to use it
+-------------
+
+Add these lines to your config file:
+
+```php
+    'modules' => [
+            'gii' => ['yii\gii\Module']
+        ]
+```
+
+Creating your own templates
+---------------------------
+
+TDB
+

docs/guide/index.md

@@ -1,50 +1,61 @@
 Introduction
 ============
 
-- [Overview](overview.md)
+- [Overview](overview.md) - What is Yii and what is it good for?
 
 Getting started
 ===============
 
-- [Installation](installation.md)
+- [Upgrading from 1.1 to 2.0](upgrade-from-v1.md)
-- [Configuration](configuration.md)
+- [Installation](installation.md) - How to download Yii and configure the Webserver?
+- [Configuration](configuration.md) - Configuration of a Yii application
 
-Application templates
+- [Basic Application Template](apps-basic.md) - A template to start a basic frontend application.
-=====================
+- [Advanced Application Template](apps-advanced.md) - The basis for more advanced applications.
 
-- [Basic](apps-basic.md)
+- [Creating your own Application structure](apps-own.md) - Learn how to start from scratch.
-- [Advanced](apps-advanced.md)
-- [Creating your own application template](apps-own.md)
 
 Base concepts
 =============
 
-- [MVC Overview](mvc.md)
+- [Basic concepts of Yii] - The Object and Component class, Path aliases and autoloading
-- [Model](model.md)
+- [MVC](mvc.md) - Implementation of MVC in Yii and a typical MVC application flow
-- [View](view.md)
+  - [Model](model.md) - The Yii Model provides Attributes, Scenarios and data Validation
-- [Controller](controller.md)
+  - [View](view.md) - Rendering Views applying layouts, using Widgets and asset management
-- [Application](application.md)
+  - [Controller](controller.md) - controller actions, routing and action filters
+- [Event Handling](events.md) - The Yii event handling mechanism
+- [Behaviors](behaviors.md)
 
 Database
 ========
 
-- [Basics](database-basics.md)
+- [Basics](database-basics.md) - Connecting to a database, basic queries, transactions and schema manipulation
-- [Query Builder](query-builder.md)
+- [Query Builder](query-builder.md) - Querying the database using a simple abstraction layer
-- [ActiveRecord](active-record.md)
+- [ActiveRecord](active-record.md) - The active record ORM, retrieving and manipulatings records and defining relations
-- [Database Migration](migration.md)
+- [Database Migration](migration.md) - Versioning your database with database migrations
 
-Extensions
+Developers Toolbox
-==========
+==================
 
+- [Automatic Code Generation](gii.md)
+- [Debug toolbar and debugger](debugger.md)
+- [Error Handling](error.md)
+- [Logging](logging.md)
+
+Extensions and 3rd party libraries
+==================================
+
+- [Composer](composer.md) - How to manage applications dependencies via composer
 - [Extending Yii](extension.md)
-- [Using template engines](template.md)
+- [Template engines](template.md) - Using template engines such as Smary or Twig
 
 Security and access control
 ===========================
 
-- [Authentication](authentication.md)
+- [Authentication](authentication.md) - Identifying User
-- [Authorization](authorization.md)
+- [Authorization](authorization.md) - Access control and RBAC
-- [Security](security.md)
+- [Security](security.md) - Hashing and verifying passwords, encryption
+- [Views security](view.md#security) - how to prevent XSS
 - Role based access control
 
 Data providers, lists and grids
@@ -55,27 +66,21 @@ Data providers, lists and grids
 - Grids
 - Lists
 
-Toolbox
+Advanced Topics
-=======
+===============
-
-- [Automatic Code Generation](gii.md)
-- [Debug toolbar and debugger](debugger.md)
-- [Error Handling](error.md)
-- [Logging](logging.md)
-
-More
-====
 
-- [Bootstrap widgets](bootstrap-widgets.md)
 - [Working with forms](form.md)
-- [Model validation reference](validation.md)
+- [Bootstrap widgets](bootstrap-widgets.md) - Using [twitter bootstrap](http://getbootstrap.com/)
-- [Caching](caching.md)
-- [Internationalization](i18n.md)
-- [URL Management](url.md)
 - [Theming](theming.md)
+- [Caching](caching.md) - Caching data, page fragments and http requests
+- [Internationalization](i18n.md) - Message translation and formatting
+- [URL Management](url.md) - routing, customized urls and SEO
 - [Console Application](console.md)
 - [Performance Tuning](performance.md)
-- [Managing assets](assets.md)
 - [Testing](testing.md)
-- [Composer](composer.md)
+
-- [Upgrading from 1.1 to 2.0](upgrade-from-v1.md)
+References
+==========
+
+- [Model validation reference](validation.md)
+- [Official Composer documentation](http://getcomposer.org)

docs/guide/installation.md

@@ -3,8 +3,9 @@ Installation
 
 There are two ways you can install the Yii framework:
 
-* Using [Composer](http://getcomposer.org/)
+* Installation via [Composer](http://getcomposer.org/) (recommended)
-* Via manual download
+* Download an application template packed with all requirements including the Yii Framework
+
 
 Installing via Composer
 -----------------------
@@ -21,48 +22,81 @@ For problems or more information, see the official Composer guide:
 * [Linux](http://getcomposer.org/doc/00-intro.md#installation-nix) 
 * [Windows](http://getcomposer.org/doc/00-intro.md#installation-windows)
 
-With Composer installed, you can create a new Yii site using one of Yii's ready-to-use application templates. Based on your needs, choosing the right template can help bootstrap your project.
+With Composer installed, you can create a new Yii site using one of Yii's ready-to-use application templates.
+Based on your needs, choosing the right template can help bootstrap your project.
 
 Currently, there are two application templates available:
 
-- [basic](https://github.com/yiisoft/yii2-app-basic), just a basic frontend application template.
+- The [Basic Application Template](https://github.com/yiisoft/yii2-app-basic) - just a basic frontend application template.
-- [advanced](https://github.com/yiisoft/yii2-app-advanced), consisting of a  frontend, a backend, console resources, common (shared code), and support for environments.
+- The [Advanced Application Template](https://github.com/yiisoft/yii2-app-advanced) - consisting of a  frontend, a backend,
+  console resources, common (shared code), and support for environments.
+
+For installation instructions for these templates, see the above linked pages.
+To read more about the ideas behind these application templates and proposed usage,
+refer to the [basic application template](apps-basic.md) and [advanced application template](apps-advanced.md) documents.
+
+If you do not want to use a template and want to start from scratch you'll find information in the document about
+[creating your own application structure](apps-own.md). This is only recommended for advanced users.
 
-For installation instructions for these templates, see the above linked pages. To read more about ideas behind these application templates and
-proposed usage, refer to the [basic application template](apps-basic.md) and [advanced application template](apps-advanced.md) documents.
 
 Installing from zip
 -------------------
 
 Installation from a zip file involves two steps:
 
-   1. Downloading the Yii Framework from [yiiframework.com](http://www.yiiframework.com/).
+   1. Downloading an application template from [yiiframework.com](http://www.yiiframework.com/download/).
    2. Unpacking the downloaded file.
 
+If you only want the Yii Framework files you can download a ZIP file directly from [github](https://github.com/yiisoft/yii2-framework/releases).
+To create your application you might want to follow the steps described in [creating your own application structure](apps-own.md).
+This is only recommended for advanced users.
+
 > Tip: The Yii framework itself does not need to be installed under a web-accessible directory.
-A Yii application has one entry script which is usually the only file that absolutely must be exposed to web users (i.e., placed within the web directory). Other PHP scripts, including those part of the
+A Yii application has one entry script which is usually the only file that absolutely must be
-Yii framework, should be protected from web access to prevent possible exploitation by hackers.
+exposed to web users (i.e., placed within the web directory). Other PHP scripts, including those
+part of the Yii Framework, should be protected from web access to prevent possible exploitation by hackers.
+
 
 Requirements
 ------------
 
 After installing Yii, you may want to verify that your server satisfies
 Yii's requirements. You can do so by running the requirement checker
-script in a web browser.
+script in a web browser or from the command line.
+
+If you have installed a Yii application template via zip or composer you'll find a `requirements.php` file in the
+base directory of your application.
 
-1. Copy the `requirements` folder from the downloaded Yii directory to your web directory.
+In order to run this script on the command line use the following command:
-2. Access `http://hostname/path/to/yii/requirements/index.php` in your browser.
+
+```
+php requirements.php
+```
+
+In order to run this script in your browser, you should ensure it is accessable by the webserver and
+access `http://hostname/path/to/yii-app/requirements.php` in your browser.
+If you are using Linux you can create a hard link to make it accessable, using the following command:
+
+```
+ln requirements.php ../requirements.php
+```
+
+Yii 2 requires PHP 5.4.0 or higher. Yii has been tested with the [Apache HTTP server](http://httpd.apache.org/) and
+[Nginx HTTP server](http://nginx.org/) on Windows and Linux.
+Yii may also be usable on other web servers and platforms, provided that PHP 5.4 or higher is supported.
 
-Yii 2 requires PHP 5.4.0 or higher. Yii has been tested with the [Apache HTTP server](http://httpd.apache.org/) on Windows and Linux. Yii may also be usable on other web servers and platforms, provided that PHP 5.4 or higher is supported.
 
 Recommended Apache Configuration
 --------------------------------
 
-Yii is ready to work with a default Apache web server configuration. As a security measure, Yii comes with `.htaccess` files in the Yii framework and application folders to deny access to thoe restricted resources. 
+Yii is ready to work with a default Apache web server configuration. As a security measure, Yii comes with `.htaccess`
+files in the Yii framework folder to deny access to those restricted resources.
 
-By default, requests for pages in a Yii-based site go through the boostrap file, usually named `index.php`, and placed in the application's root directory. The result will be URLs in the format `http://hostname/index.php/controller/action/param/value`. 
+By default, requests for pages in a Yii-based site go through the bootstrap file, usually named `index.php`, and placed
+in the application's `web` directory. The result will be URLs in the format `http://hostname/index.php/controller/action/param/value`.
 
-To hide the bootstrap file in your URLs, add `mod_rewrite` instructions to the `.htaccess` file found in your web document root (or add the instructions to the virtual host configuration in Apache's `httpd.conf` file). The applicable instructions are:
+To hide the bootstrap file in your URLs, add `mod_rewrite` instructions to the `.htaccess` file in your web document root
+(or add the instructions to the virtual host configuration in Apache's `httpd.conf` file). The applicable instructions are:
 
 ~~~
 RewriteEngine on
@@ -74,10 +108,14 @@ RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule . index.php
 ~~~
 
+
 Recommended Nginx Configuration
 -------------------------------
 
-Yii can also be used with the popular [Nginx](http://wiki.nginx.org/) web server, so long it has PHP installed as an [FPM SAPI](http://php.net/install.fpm). Below is a sample host configuration for a Yii-based site on Nginx. The configuration identifies tells the server to send all requests for non-existent resources through the bootstrap file, resulting in "prettier" URLs without the need for `index.php` references.
+Yii can also be used with the popular [Nginx](http://wiki.nginx.org/) web server, so long it has PHP installed as
+an [FPM SAPI](http://php.net/install.fpm). Below is a sample host configuration for a Yii-based site on Nginx.
+The configuration tells the server to send all requests for non-existent resources through the bootstrap file,
+resulting in "prettier" URLs without the need for `index.php` references.
 
 ~~~
 server {
@@ -85,7 +123,7 @@ server {
 
     listen       80;
     server_name  mysite.local;
-    root         /path/to/project/webroot/directory
+    root         /path/to/project/web
 
     access_log  /path/to/project/log/access.log  main;
 

docs/guide/logging.md

@@ -0,0 +1,5 @@
+Logging
+=======
+
+
+TDB

docs/guide/mvc.md

@@ -11,12 +11,12 @@ of the user interface, such as text, images, and form elements. The *controller*
 the communication between the model and the view, acting as an agent.
 
 Besides implementing the MVC design pattern, Yii also introduces a *front-controller*, called
-`application`. The front-controller encapsulates the *execution context* for the processing of a request. This means that the front-controller collects information about a user request, and
+*application*. The front-controller encapsulates the *execution context* for the processing of a request. This means that the front-controller collects information about a user request, and
 then dispatches it to an appropriate controller for actual handling of that request. In other words, the front-controller is the primary application manager, handling all requests and delegating action accordingly.
 
 The following diagram shows the static structure of a Yii application:
 
-![Static structure of Yii application](structure.png)
+![Static structure of Yii application](images/structure.png)
 
 
 A Typical Workflow
@@ -24,18 +24,23 @@ A Typical Workflow
 
 The following diagram shows a typical workflow of a Yii application  handling a user request:
 
-![Typical workflow of a Yii application](flow.png)
+![Typical workflow of a Yii application](images/flow.png)
-
+
-1. A user makes a request of the URL `http://www.example.com/index.php?r=post/show&id=1`. The Web server handles the request by executing the bootstrap script `index.php`.
+1. A user makes a request of the URL `http://www.example.com/index.php?r=post/show&id=1`.
-2. The bootstrap script creates an [Application](/doc/guide/basics.application) instance and runs it.
+   The Web server handles the request by executing the bootstrap script `index.php`.
-3. The Application instance obtains the detailed user request information from an [application component](/doc/guide/basics.application#application-component) named `request`.
+2. The bootstrap script creates an [[Application|yii\web\Application]] instance and runs it.
-4. The application determines which [controller](/doc/guide/basics.controller) and which [action](/doc/guide/basics.controller#action) of that controller was requested. This is accomplished with the help
+3. The Application instance obtains the detailed user request information from an application component named `request`.
-of an application component named `urlManager`. For this example, the controller is `post`, which refers to the `PostController` class; and the action is `show`, whose actual meaning is determined by the controller.
+4. The application determines which [controller](controller.md) and which action of that controller was requested.
-5. The application creates an instance of the requested controller
+   This is accomplished with the help of an application component named `urlManager`.
-to further handle the user request. The controller determines that the action `show` refers to a method named `actionShow` in the controller class. It then creates and executes filters (e.g. access control, benchmarking) associated with this action. The action is then executed, if execution is allowed by the filters (e.g., if the user has permission to execute that action).
+   For this example, the controller is `post`, which refers to the `PostController` class; and the action is `show`,
-6. The action creates a `Post` [model](/doc/guide/basics.model) instance, using the underlying database table, where the ID value of the corresponding record `1`.
+   whose actual meaning is determined by the controller.
-7. The action renders a [view](/doc/guide/basics.view) named `show`, providing to the view the `Post` model instance.
+5. The application creates an instance of the requested controller to further handle the users request.
+   The controller determines that the action `show` refers to a method named `actionShow` in the controller class.
+   It then creates and executes filters (e.g. access control, benchmarking) associated with this action.
+   The action is then executed, if execution is allowed by the filters (e.g., if the user has permission to execute that action).
+6. The action creates a `Post` [model](model.md) instance, using the underlying database table, where the ID value of the corresponding record is `1`.
+7. The action renders a [view](view.md) named `show`, providing to the view the `Post` model instance.
 8. The view reads the attributes of the `Post` model instance and displays the values of those attributes.
-9. The view executes some [widgets](/doc/guide/basics.view#widget).
+9. The view executes some [widgets](view.md#widgets).
-10. The view rendering result--the output from the previous steps--is embedded in a [layout](/doc/guide/basics.view#layout) to create a complete page.
+10. The view rendering result -the output from the previous steps- is embedded in a [layout](view.md#layout) to create a complete page.
 11. The action completes the view rendering and displays the result to the user.

docs/guide/overview.md

@@ -15,13 +15,15 @@ PHP 5.4.0 or greater.
 
 For developers who want to use Yii, understanding object-oriented
 programming (OOP) is very helpful, because Yii is a pure OOP framework.
+Yii 2.0 also makes use of the latest features of PHP such as [namespaces](http://www.php.net/manual/en/language.namespaces.php)
+so you should be familiar with how they work.
 
 
 What is Yii Best for?
 ---------------------
 
 Yii is a generic Web programming framework that can be used for developing
-virtually any type of Web application.  Because it is light-weight and
+virtually any type of Web application. Because it is light-weight and
 equipped with sophisticated caching mechanisms, it is especially suited
 to high-traffic applications, such as portals, forums, content
 management systems (CMS), e-commerce projects, etc.
@@ -35,4 +37,7 @@ How does Yii Compare with Other Frameworks?
 - Yii strikes a good balance between simplicity and features.
 - Syntax and overall development usability are taken seriously by the Yii development team.
 - Performance is one of the key goals for the Yii framework.
-- The Yii development team is constantly watching what other Web frameworks are doing to see what best practices and features should be incorporated into Yii. The initial Yii release was heavily influenced by Ruby on Rails. Still, no framework or feature is being blindly copied into Yii; all decisions are based upon what's best for Web developers and in keeping with Yii's philosophy.
+- The Yii development team is constantly watching what other Web frameworks are doing to see what best practices and
+  features should be incorporated into Yii. The initial Yii release was heavily influenced by Ruby on Rails.
+  Still, no framework or feature is being blindly copied into Yii; all decisions are based upon what's best
+  for Web developers and in keeping with Yii's philosophy.

docs/guide/security.md

@@ -4,7 +4,7 @@ Security
 Good security is vital to the health and success of many websites. Unfortunately, many developers may cut corners when it comes to security due to a lack of understanding or too large of an implementation hurdle. To make your Yii-based site as secure as possible, the Yii framework has baked in several excellent, and easy to use, security features. 
 
 Hashing and verifying passwords
-------------------------------
+-------------------------------
 
 Most developers know that you cannot store passwords in plain text, but many believe it's safe to hash passwords using `md5` or `sha1`. There was a time when those hashing algorithms were sufficient, but modern hardware makes it possible to break those hashes very quickly using a brute force attack.
 

docs/guide/testing.md

@@ -0,0 +1,4 @@
+Testing
+=======
+
+TDB

docs/guide/theming.md

@@ -0,0 +1,4 @@
+Theming
+=======
+
+TDB

docs/guide/upgrade-from-v1.md

@@ -72,7 +72,7 @@ $object = Yii::createObject([
 ], $param1, $param2);
 ```
 
-
+More on configuration in [configuration](configuration.md)
 
 Events
 ------