Updated docs

01_getting_started/02_configuration.md

@@ -2,9 +2,10 @@
 
 --------------------------------------------------------
 
-* [Config Files](#config_files)
-* [Cascading configuration](#cascading_configuration)
+* [Config files](#config_files)
 * [Environment aware configuration](#environment_aware_configuration)
+	- [Setting the environment](#environment_aware_configuration:setting_the_environment)
+* [Package configuration](#package_configuration)
 
 --------------------------------------------------------
 
@@ -16,7 +17,7 @@ All of the remaining framework configuration is done by editing the files that a
 
 <a id="config_files"></a>
 
-### Config Files
+### Config files
 
 Mako config files are just simple arrays:
 
@@ -67,22 +68,16 @@ $this->config->remove('crypto.configurations.user');
 
 --------------------------------------------------------
 
-<a id="cascading_configuration"></a>
-
-### Cascading configuration
-
-Sometimes you might want to edit the configuration files of a third party package. You can edit the package config file directly but the changes you make will be overwritten when you update the package. This is where cascading config files come become handy.
-
-Lets say you have a packaged named `foobar` with a config file. Just copy the file into `app/config/packages/foobar` and the application will load that file instead of the one located in the package. This makes it possible to update the package while keeping your custom settings.
-
---------------------------------------------------------
-
 <a id="environment_aware_configuration"></a>
 
 ### Environment aware configuration
 
 Mako supports environment aware configuration. This means that you can have separate configuration files for your different environments. All you have to do is create a subdirectory with the name of your environment in the `app/config` directory and copy the environment specific files into it.
 
+<a id="environment_aware_configuration:setting_the_environment"></a>
+
+#### Setting the environment
+
 Setting the environment in Apache:
 
 ```
@@ -105,9 +100,17 @@ setenv MAKO_ENV=dev # for csh and related shells
 ```
 {.language-bash}
 
-You can also manually set the environment in the CLI using the env option.
+You can also manually set the environment in the [CLI](:base_url:/docs/:version:/command-line:basics) using the env option.
 
 ```
 php reactor <command> --env=dev
 ```
 {.language-none}
+
+--------------------------------------------------------
+
+<a id="package_configuration"></a>
+
+### Package configuration
+
+Check out the [package documentation](:base_url:/docs/:version:/packages:packages#configuration_i18n_and_views) for more information regarding package configuration.

01_getting_started/06_deployment.md

@@ -10,6 +10,10 @@
 
 --------------------------------------------------------
 
+Mako works well with all major webservers but we suggest using [Nginx](http://nginx.org) along with [php-fpm](https://php-fpm.org) for optimal performance.
+
+--------------------------------------------------------
+
 <a id="server_configuration"></a>
 
 ### Server configuration
@@ -18,7 +22,7 @@
 
 #### Nginx
 
-Basic [Nginx](http://nginx.org) configuration for a Mako application:
+Basic Nginx configuration that you can build upon:
 
 ```
 server
@@ -50,7 +54,7 @@ server
 ```
 {.language-nginx}
 
-> Note that you can also use [php-fpm](https://php-fpm.org) over a unix socket instead of tcp. Just make sure that the [rlimit_files](http://php.net/manual/en/install.fpm.configuration.php) value is lower or equal to the file descriptor limit at the OS level.
+> You can also use php-fpm over a unix socket instead of tcp. Just make sure that the [rlimit_files](http://php.net/manual/en/install.fpm.configuration.php) value is lower or equal to the file descriptor limit at the OS level.
 
 --------------------------------------------------------
 
@@ -88,8 +92,8 @@ opcache.fast_shutdown=1
 ```
 {.language-none}
 
+[Cachetool](https://github.com/gordalina/cachetool) can be used to check the OPcache status. This is useful if you want to see if you need to tweak some of the configuration values.
+
 > Note that setting `validate_timestamps` to `0` tells OPcache to never check PHP files for changes. This is great for performance but it means that you'll have to clear the bytecode cache after each deployment to ensure that your files are recompiled.
 >
-> This can be done by reloading or restarting the php-fpm process, by calling `opcache_reset()` (this must be done via php-fpm and not php-cli) or by using [cachetool](https://github.com/gordalina/cachetool).
-
-[Cachetool](https://github.com/gordalina/cachetool) can also be used to check the OPcache status. This is useful if you want to see if you need to tweak some of the configuration values.
+> This can be done by reloading or restarting the php-fpm process, by calling [`opcache_reset()`](http://php.net/manual/en/function.opcache-reset.php) (this must be done via php-fpm and not php-cli) or by using `cachetool`.

07_packages/01_packages.md

@@ -4,6 +4,7 @@
 
 * [Basics](#basics)
 * [Configuration, i18n and views](#configuration_i18n_and_views)
+	- [Overriding configuration, i18n and views](#configuration_i18n_and_views:overriding_configuration_i18n_and_views)
 * [Commands](#commands)
 * [Package installation](#package_installation)
 * [Publishing packages](#publishing_packages)
@@ -94,6 +95,16 @@ By default the file namespace of a package will be the package name where the sl
 protected $fileNamespace = 'foo';
 ```
 
+<a id="configuration_i18n_and_views:overriding_configuration_i18n_and_views"></a>
+
+#### Overriding configuration, i18n and views
+
+Sometimes you might want to modify the configuration, i18n strings or views of a third party package. You can edit the them directly but the changes you make will be overwritten when you update the package. This is where the cascading file lookup comes in handy.
+
+Lets say you have a packaged named `acme-foo` with a config file you want to modify. Just copy the file into `app/config/packages/acme-foo` and the application will load your copy instead of the one located in the package. This makes it possible to update the package while keeping your custom settings. The same convention also works for i18n and view files.
+
+> You can also override the default Mako error views using this method. Just create a `app/resources/views/packages/mako-error` directory and add a file named `404.tpl.php` to create your own custom 404 template.
+
 --------------------------------------------------------
 
 <a id="commands"></a>
@@ -120,14 +131,14 @@ protected $commands =
 Installing packages is extremely easy. All you need to do is running a simple [composer](https://getcomposer.org/) command and add the package "boot" class to the list of packages in your `app/config/application.php` configuration file.
 
 ```
-composer require <vendor>/<package name>:*
+composer require <vendor>/<package name>
 ```
 {.language-none}
 
 So, to install `acme/foo` package using composer, you have to issue following command from the project directory
 
 ```
-composer require acme/foo:*
+composer require acme/foo
 ```
 {.language-none}