Final fixes!!!!!!!!!!!!!!!!!!!!

and final 'i like to add links, commas, parenthesis, and... verbosity ;)
well, Christian, THANKS for your patience and cooperation. #Done

audit/main.md

@@ -3,7 +3,7 @@
 The Audit class is a data validator.
 
 Namespace: `\` <br>
-File location: `lib/./lib/audit.php.php`
+File location: `lib/audit.php`
 
 ---
 

base/main.md

@@ -1071,7 +1071,13 @@ $f3->route(
     'GET /archive/@year/@month/@day'
   ),
   function($f3,$params){
-    $params+=array('year'=>2013,'month'=>1,'day'=>1); //default values
+	$yesterday = time()-86400; // archives of yesterday if nothing else specified
+	$def_day   = isset($params['day'])   ? $params['day']   : date('j',$yesterday);
+	$def_month = isset($params['month']) ? $params['month'] : date('m',$yesterday);
+	$def_year  = isset($params['year'])  ? $params['year']  : date('y',$yesterday);
+	$params+=array('year'  => $def_year,
+				   'month' => $def_month,
+				   'day'   => $def_day);     //set default values
     //etc..
   }
 );
@@ -1185,7 +1191,7 @@ After processing the incoming request URI, the routing pattern that matches that
 The `PARAMS` var will contains all tokens as named keys, and additionally all tokens and wildcards as numeric keys, depending on their order of appearance.
 
 <div class="alert alert-info">
-    <p><b>Notice:</b> If a static and dynamic route pattern both match the current URI, then the static route pattern has priority.</p>
+	<p><b>Notice:</b> If a static and dynamic route pattern both match the current URI, then the <em>static</em> route pattern has priority.</p>
 </div>
 
 
@@ -1206,7 +1212,7 @@ This method provides that facility to invoke callbacks and their arguments. F3 r
 
 `$args` if specified provides a means of executing the callback with parameters.
 
-`$hooks` is used by the `route()` method to specify pre- and post-execution functions, i.e. `beforeroute()` and `afterroute()`.
+`$hooks` is used by the `route()` method to specify pre- and post-execution functions, i.e. `beforeroute()` and `afterroute()`. (refer to the section [Event Handlers](routing-engine#event-handlers) for more explanations about `beforeroute()` and `afterroute()`)
 
 ### chain
 
@@ -1327,6 +1333,17 @@ echo $f3->rel( 'http://fatfreeframework.com/gui/img/supported_dbs.jpg' ); // 'gu
 
 ## Misc
 
+### Instantiation
+
+**Return class instance**
+
+```php
+$f3 = \Base::instance();
+```
+
+This is used to grab the framework instance at any point of your code.
+
+
 ### blacklisted
 
 **Lookup visitor's IP against common DNS blacklist services**
@@ -1362,31 +1379,6 @@ null dump ( mixed $expr )
 
 <i class="icon-thumbs-up"></i> _NOTICE: The syntax highlighting depends on the [DEBUG level](quick-reference#debug "The DEBUG system variable")_.
 
-### error
-
-**Execute error handler**
-
-```php
-null error ( int $code [, string $text = '' [, array $trace = NULL ]] )
-```
-
-Calling this function logs an error and executes the [ONERROR](quick-reference#onerror) handler if defined.
-Otherwise it will display a default error page in HTML for synchronous requests, or gives a JSON string for AJAX requests.
-
-### expire
-
-**Send cache metadata to HTTP client**
-
-```php
-void expire ( [ int $secs = 0 ] )
-```
-
-There is little need to call this method directly because it is automatically invoked at runtime by the framework, depending on whether the page should be cached  or otherwise. The framework sends the necessary HTTP cache control headers to the browser so you don't need to send it yourself.
-
-```php
-$f3->expire(0); // sends 'Cache-Control: no-cache, no-store, must-revalidate'
-```
-
 ### highlight
 
 **Apply syntax highlighting**
@@ -1395,7 +1387,7 @@ $f3->expire(0); // sends 'Cache-Control: no-cache, no-store, must-revalidate'
 string highlight ( string $text )
 ```
 
-Applies syntax highlighting to a given string and returns the highlighed string.
+Applies syntax highlighting to a given string and returns the highlighted string.
 
 Example:
 
@@ -1407,19 +1399,25 @@ Returns:
 ```html
 <code><span class="variable">$fatfree</span><span class="object_operator">-&gt;</span><span class="string">rocks</span><span>(</span><span class="constant_encapsed_string">'FAST'</span><span class="whitespace"> </span><span class="logical_and">AND</span><span class="whitespace"> </span><span class="variable">$light</span><span>)</span></code>
 ```
-<div class="alert alert-warning">Keep in mind you need the `code.css` stylesheet to see correctly see the syntax highlighting in your browser pages. You can include it in your pages with &lt;link href="code.css" rel="stylesheet"&gt;&lt;/code&gt; (code.css is bundled into the framework 'lib/' folder)</div>
-
+<div class="alert alert-warning">Keep in mind you need the `code.css` stylesheet to correctly see the syntax highlighting in your browser pages. You can include it in your pages with &lt;link href="code.css" rel="stylesheet" /&gt; (code.css is bundled into the framework 'lib/' folder)</div>
 
-### instance
+### compile
 
-**Return class instance**
+**Convert JS-style token to PHP expression**
 
 ```php
-$f3 = \Base::instance();
+string compile ( string $str )
 ```
+This method is mainly used by the [Preview class](preview), the lightweight template engine, to convert tokens to variables.
 
-This is used to grab the framework instance at any point of your code.
+Example:
+
+```php
+compile ('The sun was so {{@RAINBOW.cyan}} today');
 
+// returns:
+'The sun was so $RAINBOW['cyan'] today'
+```
 
 ### status
 
@@ -1437,6 +1435,31 @@ $f3->status(407); // Sends a '407 Proxy Authentication Required' client error
 $f3->status(503); // Sends a '503 Service Unavailable' server error
 ```
 
+### error
+
+**Execute error handler**
+
+```php
+null error ( int $code [, string $text = '' [, array $trace = NULL ]] )
+```
+
+Calling this function logs an error and executes the [ONERROR](quick-reference#onerror) handler if defined.
+Otherwise it will display a default error page in HTML for synchronous requests, or gives a JSON string for AJAX requests.
+
+### expire
+
+**Send cache metadata to HTTP client**
+
+```php
+void expire ( [ int $secs = 0 ] )
+```
+
+There is little need to call this method directly because it is automatically invoked at runtime by the framework, depending on whether the page should be cached  or otherwise. The framework sends the necessary HTTP cache control headers to the browser so you don't need to send it yourself.
+
+```php
+$f3->expire(0); // sends 'Cache-Control: no-cache, no-store, must-revalidate'
+```
+
 ### unload
 
 **Execute framework/application shutdown sequence**

cache/main.md

@@ -3,7 +3,7 @@
 This class represents F3's multi protocol Cache engine. It supports [Memcache](http://memcached.org/), [WinCache](http://www.iis.net/downloads/microsoft/wincache-extension), [APC](http://php.net/manual/en/book.apc.php), [XCache](http://xcache.lighttpd.net/) and filesystem based caching.
 
 Caching is a powerful way to get more performance out of your application. It is seamlessly integrated to all core and plugin features
-like [setting hive keys](base#set), [HTTP responses](base#caching), DB queries and even to [JS/CSS minification](optimization#keeping-javascript-and-css-on-a-healthy-diet).
+like [setting hive keys](base#set), [HTTP responses](base#caching), DB mappers and queries and even to [JS/CSS minification](optimization#keeping-javascript-and-css-on-a-healthy-diet).
 
 There is a good [Cache Engine User Guide](optimization#cache-engine) that covers how the cache engine works and gives you tips to improve your application and your database queries, as they can be cached by F3 as well. You really should have read it.
 

databases/main.md

@@ -22,7 +22,7 @@ $db=new DB\SQL(
 
 ## Querying the Database
 
-OK. That was easy, wasn't it? That's pretty much how you would do the same thing in ordinary PHP. You just need to know the DSN format of the database you're connecting to. See the PDO section of the PHP manual.
+OK. That was easy, wasn't it? That's pretty much how you would do the same thing in ordinary PHP. You just need to know the DSN format of the database you're connecting to. See the [PDO section of the PHP manual](http://www.php.net/manual/en/pdo.connections.php "PHP Data Objects :: Connections").
 
 Let's continue our PHP code:
 
@@ -156,11 +156,11 @@ $user=new DB\SQL\Mapper($db,'users');
 $user->load(array('userID=?','tarzan'));
 ```
 
-The first line instantiates a data mapper object that interacts with the `users` table in our database. Behind the scene, F3 retrieves the structure of the `users` table and determines which field(s) are defined as primary key(s). At this point, the mapper object contains no data yet (dry state) so `$user` is nothing more than a structured object - but it contains the methods it needs to perform the basic CRUD operations and some extras. To retrieve a record from our users table with a `userID` field containing the string value `tarzan`, we use the `load() method`. This process is called "auto-hydrating" the data mapper object.
+The first line instantiates a data mapper object that interacts with the `users` table in our database. Behind the scene, F3 retrieves the structure of the `users` table and determines which field(s) are defined as primary key(s). At this point, the mapper object does not contains any data yet (it is called in "dry state") and the `$user` var is basically nothing more than a structured object - but containing the methods it needs to perform the basic CRUD operations plus some extras as you will see later. Now, to retrieve a record from our `users` table with, e.g., the field `userID` containing the string value `tarzan`, we use the `load()` method. This process is called "auto-hydrating" the data mapper object.
 
-Easy, wasn't it? F3 understands that a SQL table already has a structural definition existing within the database engine itself. Unlike other frameworks, F3 requires no extra class declarations (unless you want to extend the data mappers to fit complex objects), no redundant PHP array/object property-to-field mappings (duplication of efforts), no code generators (which require code regeneration if the database structure changes), no stupid XML/YAML files to configure your models, no superfluous commands just to retrieve a single record. With F3, a simple resizing of a `varchar` field in MySQL does not demand a change in your application code. Consistent with MVC and "separation of concerns", the database admin has as much control over the data (and the structures) as a template designer has over HTML/XML templates.
+Easy, wasn't it? F3 understands that a SQL table already has a structural definition existing within the database engine itself. Unlike other frameworks, F3 requires no extra class declarations (unless you want to extend the data mappers to fit complex objects), no redundant PHP array/object property-to-field mappings (duplication of efforts), no code generators (which require code regeneration when the database structure changes), no stupid XML/YAML files to configure your models, no superfluous commands just to retrieve a single record. With F3, a simple resizing of a `varchar` field in your MySQL table does not require a single change in your application code. Consistent with MVC and "separation of concerns", the database admin has as much control over the data and the structures as a template designer has over HTML/XML templates.
 
-If you prefer working with NoSQL databases, the similarities in query syntax are superficial. In the case of the MongoDB data mapper, the equivalent code would be:
+If you prefer working with NoSQL databases, the similarities in query syntax are immediate. In the case of the MongoDB data mapper, the equivalent code would be:
 
 ```php
 $db=new DB\Mongo('mongodb://localhost:27017','testdb');
@@ -180,13 +180,13 @@ $user->load(array('@userID=?','tarzan'));
 
 The framework automatically maps the field `visits` in our table to a data mapper property during object instantiation, i.e. `$user=new DB\SQL\Mapper($db,'users');`. Once the object is created, `$user->password` and `$user->userID` would map to the `password` and `userID` fields in our table, respectively.
 
-You can't add or delete a mapped field, or change a table's structure using the ORM. You must do this in MySQL, or whatever database engine you're using. After you make the changes in your database engine, Fat-Free will automatically synchronize the new table structure with your data mapper object when you run your application.
+You can't add or delete a mapped field, or change a table structure using the ORM. You must do this in MySQL, or whatever database engine you're using. After you've made the changes in your database engine, Fat-Free will automatically synchronize the new table structure with your data mapper object when you run your application.
 
 F3 derives the data mapper structure directly from the database schema. No guesswork involved. It understands the differences between MySQL, SQLite, MSSQL, Sybase, and PostgreSQL database engines.
 
-SQL identifiers should not use reserved words, and should be limited to alphanumeric characters `A-Z`, `0-9`, and the underscore symbol (`_`). Column names containing spaces (or special characters) and surrounded by quotes in the data definition are not compatible with the ORM. They cannot be represented properly as PHP object properties.
+<div class="alert alert-warning"><strong>Notice:</strong> SQL identifiers should not use reserved words, and should be limited to alphanumeric characters `A-Z`, `0-9`, and the underscore symbol (`_`). Column names containing spaces (or special characters) and surrounded by quotes in the data definition are not compatible with the ORM. They cannot be represented properly as PHP object properties.</div>
 
-Let's say we want to increment the user's number of visits and update the corresponding record in our users table, we can add the following code:
+Let's say now we want to increment the user's number of visits and update the corresponding record in our `users` table, we can add the following code:
 
 ```php
 $user->visits++;

image/main.md

@@ -136,7 +136,7 @@ $img->crop( int $x1, int $y1, int $x2, int $y2);
 **Resize image (Maintain aspect ratio)**
 
 ```php
-$img->resize( int $width, int $height, [ bool $crop = TRUE ], [ bool $enlarge = TRUE ]);
+$img->resize( int $width, int $height [, bool $crop = TRUE [, bool $enlarge = TRUE ]] );
 ```
 
 If `$crop` is `TRUE` the image will be resized to fit with its smallest side into the resize box.
@@ -155,7 +155,7 @@ $img->rotate( int $angle );
 **Apply an image overlay**
 
 ```php
-$img->overlay( Image $img, [ bool|int $align = NULL ]);
+$img->overlay( Image $img [, bool|int $align = NULL ] );
 ```
 
 This is used to merge to images, i.e. for watermarks. You need to provide another Image object and can align that by the bitwise `$align` argument.
@@ -191,7 +191,7 @@ y - align:
 **Generate identicon**
 
 ```php
-$img->identicon( string $str, [ int $size = 64 ], [ int $blocks = 4 ]);
+$img->identicon( string $str [, int $size = 64 [, int $blocks = 4 ]] );
 ```
 
 This method renders a unique [identicon](http://en.wikipedia.org/wiki/Identicon) based on the given `$str`.
@@ -201,7 +201,7 @@ The `$size` argument defines the width and height of the resulting image. `$bloc
 **Generate CAPTCHA image**
 
 ```php
-$img->captcha( string $font, [ int $size = 24 ], [ int $len = 5 ], [ string|bool $key = NULL], [ string $path='' ], [ $foregroundcolor=0xFFF ], [ $backgroundcolor=0x000 ] );
+$img->captcha( string $font [, int $size = 24 [, int $len = 5 [, string|bool $key = NULL [, string $path='' [, $foregroundcolor=0xFFF [, $backgroundcolor=0x000 ]]]]]] );
 ```
 
 This renders a captcha image. Please have a look to this [user guide section about rendering captcha images](plug-ins#captcha-images), to see a little example.
@@ -277,7 +277,7 @@ This will create a new temporary image of the current state.
 **Revert to specified state**
 
 ```php
-$img->restore([ int $state = 1 ]);
+$img->restore( [ int $state = 1 ] );
 ```
 
 This fetches the original image state from the temp folder.

jig-mapper/main.md

@@ -43,7 +43,7 @@ The `$filter` argument for Jig accepts the following structure:
 
 ```php
 // array value for parameterized queries
-array( string $expr, [ string $bindValue1 ], [ string $bindValue2 ], [...] )
+array( string $expr [, string $bindValue1 [, string $bindValue2 [, ...]]] )
 ```
 
 The `$expr` part must contain a valid code expression, where all mapper fields are prefixed by a `@`-char. You can bind values to them with positional or named tokens.

log/main.md

@@ -22,7 +22,7 @@ If the file and folder does not exist, the Logger tries to create them.
 **Write specified text to log file**
 
 ```php
-$logger->write( string $text, [ string $format = 'r' ]);
+$logger->write( string $text [, string $format = 'r' ] );
 ```
 
 The `$format` argument defines the date format that is going to be added to the log line. The default value `r` specifies a RFC 2822 compliant date format that looks like `Thu, 21 Dec 2000 16:01:07 +0200`.  The remote address is also added to the log entry.

routing-engine/main.md

@@ -418,7 +418,7 @@ will instantiate the `Home` class at runtime and call the `show()` method therea
 ## Event Handlers
 
 F3 has a couple of routing event listeners that might help you improve the flow and structure of
-controller classes. Say you have a route defined as the following:
+controller classes. Say you have a route defined as follow:
 
 ```php
 $f3->route('GET /','Main->home');
@@ -428,11 +428,11 @@ If the application receives an HTTP request matching the above route, F3 first i
 but _before_ executing the `home()` method, the framework looks for a method in this class named
 `beforeRoute()`. If present, F3 runs the code contained in the `beforeRoute()` event
 handler before transferring control to the method specified in the route, in our example the `home()` method.
-Once the method is accomplished, the framework then looks for an `afterRoute()` event handler that is called if present.
+Once the method is terminated, the framework then looks for an `afterRoute()` event handler that is called if present.
 The `beforeroute()` and `afterroute()` event handlers are common to a given class. 
 It means if you have defined differents routes using differents methods of a same class,
 e.g. `'GET /login','User->login'` and `'GET /logout','User->logout'`, both routes will share the same
-`beforeroute()` and `afterroute()` event handlers.
+`beforeroute()` and `afterroute()` events handlers.
 
 ## Dynamic Route Handlers
 
@@ -461,7 +461,7 @@ or method associated with the current route, i.e. there is no defined class and/
 ## AJAX and Synchronous Requests
 
 Routing patterns may contain _modifiers_ that instruct the framework to base its routing decision on
-the type of HTTP request:
+the type of the HTTP request:
 
 ```php
 $f3->route('GET /example [ajax]','Page->getFragment');

session/main.md

@@ -3,18 +3,17 @@
 The framework contains some SESSION handlers as well.
 To use them, just create a new instance of the certain class once. The plugins will register a new [session_set_save_handler](http://php.net/manual/en/function.session-set-save-handler.php "php.net :: function session_set_save_handler")
 which syncs the frameworks [SESSION](quick-reference#cookie,-get,-post,-request,-session,-files,-server,-env) hive keys to the corresponding new session handler class.
-to the corresponding new session handler class.
+
+Namespace: `\` <br>
+File location: `lib/session.php`
 
 ---
 
 ### Cache
 
 The Session class provides a lightweight [Cache](cache)-based session handler.
 
-Namespace: `\` <br/>
-File location: `lib/session.php`
-
-Ensure that you have enabled the [cache](quick-reference#cache) to make this work. Usage:
+Make sure you have [enabled the cache](quick-reference#cache) to make this work. Usage:
 
 ```php
 // just create an object

sql/main.md

@@ -290,10 +290,10 @@ int type ( scalar $val )
 ```
 This function allows you to retrieve the PDO constant corresponding to the php type of the provided `$val` as follow:
 
-+ the `NULL` php type will returns `\PDO::PARAM_NULL`
-+ the `boolean` php type will returns `\PDO::PARAM_BOOL` (int 5)
-+ the `integer` php type will returns `\PDO::PARAM_INT` (int 1)
-+ and any other php type will returns `\PDO::PARAM_STR` (int 2)
++ the `NULL` php type will return `\PDO::PARAM_NULL`
++ the `boolean` php type will return `\PDO::PARAM_BOOL` (int 5)
++ the `integer` php type will return `\PDO::PARAM_INT` (int 1)
++ and any other php type will return `\PDO::PARAM_STR` (int 2)
 
 ### quote