diff --git a/docs/api/caching/basics.md b/docs/api/caching/basics.md
index e69de29b..19c04c99 100644
--- a/docs/api/caching/basics.md
+++ b/docs/api/caching/basics.md
@@ -0,0 +1,184 @@
+# Caching
+
+Caching is used to speed up the rendering of a template by saving and re-using the output. 
+
+If a cached version of the call is available, that is displayed instead of
+regenerating the output. Caching can speed things up tremendously,
+especially templates with longer computation times. 
+
+Since templates can include or extend other templates, one
+cache file could conceivably be made up of several template files,
+config files, etc.
+
+> ** Note **
+> 
+> Since templates are dynamic, it is important to be careful what you are
+> caching and for how long. For instance, if you are displaying the front
+> page of your website that does not change its content very often, it
+> might work well to cache this page for an hour or more. On the other
+> hand, if you are displaying a page with a timetable containing new
+> information by the minute, it would not make sense to cache this page.
+
+## Setting Up Caching
+
+The first thing to do is enable caching by calling `Smarty::setCaching()` with either
+`\Smarty\Smarty::CACHING_LIFETIME_CURRENT` or `\Smarty\Smarty::CACHING_LIFETIME_SAVED`.
+Or with `\Smarty\Smarty::CACHING_OFF` to disable caching again.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+// enable caching, using the current lifetime (see below)
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+// enable caching, using the lifetime set when the cache was saved (see below)
+$smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
+
+// disable caching
+$smarty->setCaching(Smarty::CACHING_OFF);
+
+$smarty->display('index.tpl');
+```
+
+With caching enabled, the function call to `$smarty->display('index.tpl')` will
+render the template as usual, but also saves a copy of its output. On the
+next call to `$smarty->display('index.tpl')`, the cached copy will be used
+instead of rendering the template again.
+
+> **Note**
+>
+> By default, Smarty saved its caches as files in a dir called `cache` relative to the current 
+> directory. The default directory can be changed using `$smarty->setCacheDir('/some/cache/dir');` 
+> The files are named similar
+> to the template name. Although they end in the `.php` extension, they
+> are not intended to be directly executable. Do not edit these files!
+
+## Cache lifetime
+
+Each cached page has a limited lifetime. The default value is 3600
+seconds, or one hour. After that time expires, the cache is regenerated.
+
+You can change the lifetime as follows:
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT); 
+// or $smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
+
+// set the cache_lifetime to 5 minutes
+$smarty->setCacheLifetime(5 * 60);
+```
+
+Setting caching to a value of `\Smarty\Smarty::CACHING_LIFETIME_CURRENT` tells Smarty to use
+the current lifetime to determine if the cache has expired.
+
+A value of `\Smarty\Smarty::CACHING\_LIFETIME\_SAVED` tells Smarty to use the lifetime value at the time the
+cache was generated. This way you can set the just before rendering a template to have granular control over
+when that particular cache expires.
+
+An example:
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+// retain current cache lifetime for each specific display call
+$smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
+
+// set the cache_lifetime for index.tpl to 5 minutes
+$smarty->setCacheLifetime(300);
+$smarty->display('index.tpl');
+
+// set the cache_lifetime for home.tpl to 1 hour
+$smarty->setCacheLifetime(3600);
+$smarty->display('home.tpl');
+
+// NOTE: the following $cache_lifetime setting will not work when $caching
+// is set to Smarty::CACHING_LIFETIME_SAVED.
+// The cache lifetime for home.tpl has already been set
+// to 1 hour, and will no longer respect the value of $cache_lifetime.
+// The home.tpl cache will still expire after 1 hour.
+$smarty->setCacheLifetime(30); // 30 seconds
+$smarty->display('home.tpl');
+```
+
+## Compile check
+
+By default, every template file and config file that is involved with the cache file
+is checked for modification. If any of the files have been modified
+since the cache was generated, the cache is immediately regenerated.
+
+This is a computational overhead, so for optimum performance, disable this on a production environment:
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+$smarty->setCompileCheck(Smarty::COMPILECHECK_OFF);
+
+$smarty->display('index.tpl');
+```
+
+## Checking if a template is cached
+
+Smarty's `isCached() method can be used to test if a
+template has a valid cache or not. If you have a cached template that
+requires something like a database fetch, you can use this to skip that
+process.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+if (!$smarty->isCached('index.tpl')) {
+    // No cache available, do variable assignments here.
+    $smarty->assign('data', do_expensive_database_calls());
+}
+
+$smarty->display('index.tpl');
+```
+
+## Nocache-blocks
+You can keep parts of a page dynamic (disable caching) with the
+[`{nocache}{/nocache}`](../../designers/language-builtin-functions/language-function-nocache.md) block function, 
+or by using the `nocache` parameter for most template functions.
+
+Let's say the whole page can be cached except for a banner that is
+displayed down the side of the page. By using a [`{nocache}{/nocache}`](../../designers/language-builtin-functions/language-function-nocache.md)
+block for the banner, you can
+keep this element dynamic within the cached content.
+
+## Clearing the cache
+You can clear all the cache files with Smarty's `clearAllCache()` method, or individual cache
+files with the `clearCache()` method.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+// clear only cache for index.tpl
+$smarty->clearCache('index.tpl');
+
+// clear out all cache files
+$smarty->clearAllCache();
+
+// clear out all cache files older than one hour
+$smarty->clearAllCache(3600);
+
+// or, clear all expired caches
+$smarty->clearAllCache(Smarty::CLEAR_EXPIRED);
+```
+
+        
diff --git a/docs/api/caching/custom-storage-layers.md b/docs/api/caching/custom-storage-layers.md
index e69de29b..f43e724e 100644
--- a/docs/api/caching/custom-storage-layers.md
+++ b/docs/api/caching/custom-storage-layers.md
@@ -0,0 +1,36 @@
+# Custom cache storage layers
+
+As an alternative to using the default file-based caching mechanism, you
+can specify a custom cache implementation that will be used to read,
+write and clear cached files.
+
+With a custom cache implementation you could replace the slow filesystem by a
+faster storage engine, centralize the cache to be accessible to multiple
+servers.
+
+Smarty requires implementations to extend `\Smarty\Cacheresource\Base`, but encourages you to either extend 
+`\Smarty\Cacheresource\Custom` or `\Smarty\Cacheresource\KeyValueStore`.
+
+- `\Smarty\Cacheresource\Custom` is a simple API directing all read, write,
+clear calls to your implementation. This API allows you to store
+wherever and however you deem fit. 
+- `\Smarty\Cacheresource\KeyValueStore` allows you to turn any 
+KeyValue-Store (like APC or Memcache) into a full-featured
+CacheResource implementation. Everything around deep
+cache-groups like "a|b|c" is being handled for you in a way that
+guarantees clearing the cache-group "a" will clear all nested groups 
+as well - even though KeyValue-Stores don't allow this kind of
+hierarchy by nature.
+
+Custom CacheResources must be registered on
+runtime with `Smarty\Smarty::setCacheResource()`:
+
+```php
+<?php
+
+use Smarty\Smarty;
+$smarty = new Smarty();
+
+$smarty->setCacheResource(new My_CacheResource_Mysql());
+```
+       
diff --git a/docs/api/caching/multiple-caches-per-pages.md b/docs/api/caching/multiple-caches-per-pages.md
deleted file mode 100644
index e69de29b..00000000
diff --git a/docs/api/caching/multiple-caches-per-template.md b/docs/api/caching/multiple-caches-per-template.md
new file mode 100644
index 00000000..c3da9d0a
--- /dev/null
+++ b/docs/api/caching/multiple-caches-per-template.md
@@ -0,0 +1,137 @@
+# Multiple caches per template
+
+## Introduction
+
+You can have multiple cache files for a single call to
+`display()` or `fetch()`. 
+
+Let's say that
+a call to `$smarty->display('index.tpl')` may have several different output
+contents depending on some condition, and you want separate caches for
+each one. You can do this by passing a `$cache_id` as the second
+parameter to the function call:
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+$my_cache_id = (int) $_GET['article_id'];
+
+$smarty->display('index.tpl', $my_cache_id);
+```
+
+
+Above, we are passing the variable `$my_cache_id` to
+[`display()`](#api.display) as the `$cache_id`. For each unique value of
+`$my_cache_id`, a separate cache will be generated for `index.tpl`. In
+this example, `article_id` was passed in the URL and is used as the
+`$cache_id`.
+
+> **Note**
+>
+> Be very cautious when passing values from a client (web browser) into
+> Smarty or any PHP application. Although the above example of using the
+> article_id from the URL looks handy, it could have bad consequences.
+> The `$cache_id` is used to create a directory on the file system, so
+> if the user decided to write a script that sends random article_id's at a rapid pace,
+> this could possibly cause problems at the server level.
+> Be sure to sanitize any data passed in before using it. In this example, you might want to check if
+> the article_id is a valid ID in the database.
+
+Be sure to pass the same `$cache_id` as the second parameter to
+`isCached()` and `clearCache()`.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+$my_cache_id = (int) $_GET['article_id'];
+
+if (!$smarty->isCached('index.tpl', $my_cache_id)) {
+    // ...
+}
+
+$smarty->display('index.tpl', $my_cache_id);
+```
+
+## Clearing specific caches
+
+You can clear all caches for a particular `$cache_id` by passing NULL as
+the first parameter to `clearCache()`.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+// clear all caches with "sports" as the $cache_id
+$smarty->clearCache(null, 'sports');
+
+$smarty->display('index.tpl', 'sports');
+```
+
+In this manner, you can "group" your caches together by giving them the
+same `$cache_id`.
+
+## Advanced cache grouping
+
+You can do more elaborate grouping by setting up `$cache_id` groups.
+This is accomplished by separating each sub-group with a vertical bar
+`|` in the `$cache_id` value. You can have as many sub-groups as you
+like.
+
+-   You can think of cache groups like a directory hierarchy. For
+    instance, a cache group of `'a|b|c'` could be thought of as the
+    directory structure `'/a/b/c/'`.
+
+-   `clearCache(null, 'a|b|c')` would be like removing the files
+    `'/a/b/c/*'`. `clearCache(null, 'a|b')` would be like removing the
+    files `'/a/b/*'`.
+
+-   If you specify a template name such as
+    `clearCache('foo.tpl', 'a|b|c')` then Smarty will attempt to remove
+    `'/a/b/c/foo.tpl'`.
+
+-   You CANNOT remove a specified template name under multiple cache
+    groups such as `'/a/b/*/foo.tpl'`, the cache grouping works
+    left-to-right ONLY. You will need to group your templates under a
+    single cache group hierarchy to be able to clear them as a group.
+
+Cache grouping should not be confused with your template directory
+hierarchy, the cache grouping has no knowledge of how your templates are
+structured. So for example, if you have a template structure like
+`themes/blue/index.tpl` and you want to be able to clear all the cache
+files for the "blue" theme, you will need to create a cache group
+structure that mimics your template file structure, such as
+`display('themes/blue/index.tpl', 'themes|blue')`, then clear them with
+`clearCache(null, 'themes|blue')`.
+
+```php
+<?php
+use Smarty\Smarty;
+$smarty = new Smarty;
+
+$smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
+
+// clear all caches with 'sports|basketball' as the first two cache_id groups
+$smarty->clearCache(null, 'sports|basketball');
+
+// clear all caches with "sports" as the first cache_id group. This would
+// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
+$smarty->clearCache(null, 'sports');
+
+// clear the foo.tpl cache file with "sports|basketball" as the cache_id
+$smarty->clearCache('foo.tpl', 'sports|basketball');
+
+$smarty->display('index.tpl', 'sports|basketball');
+```
+
+          
diff --git a/docs/designers/language-builtin-functions/language-function-nocache.md b/docs/designers/language-builtin-functions/language-function-nocache.md
index e6d8453f..7997ecfb 100644
--- a/docs/designers/language-builtin-functions/language-function-nocache.md
+++ b/docs/designers/language-builtin-functions/language-function-nocache.md
@@ -17,4 +17,4 @@ Today's date is
    
 The above code will output the current date on a cached page.
 
-See also the [caching section](../../programmers/caching.md).
+See also the [caching section](../../api/caching/basics.md).
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a827b4a3..0bab5aa0 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -33,13 +33,8 @@ $smarty = new Smarty();
 Now that the library files are in place, it's time to set up the Smarty
 directories for your application.
 
-Smarty requires four directories which are by default named
-    [`templates`](./programmers/api-variables/variable-template-dir.md),
-    [`configs`](./programmers/api-variables/variable-config-dir.md),
-    [`templates_c`](./programmers/api-variables/variable-compile-dir.md)
-     and 
-    [`cache`](./programmers/api-variables/variable-cache-dir.md) 
-    relative to the current working directory.
+Smarty requires four directories which are by default named `templates`, `configs`, `templates_c` and `cache` 
+relative to the current working directory.
 
 The defaults can be changed as follows:
 
diff --git a/docs/programmers/caching.md b/docs/programmers/caching.md
deleted file mode 100644
index 5656b71b..00000000
--- a/docs/programmers/caching.md
+++ /dev/null
@@ -1,24 +0,0 @@
-Caching
-=======
-
-Caching is used to speed up a call to [`display()`](./api-functions/api-display.md) or
-[`fetch()`](./api-functions/api-fetch.md) by saving its output to a file. If a cached
-version of the call is available, that is displayed instead of
-regenerating the output. Caching can speed things up tremendously,
-especially templates with longer computation times. Since the output of
-[`display()`](./api-functions/api-display.md) or [`fetch()`](./api-functions/api-fetch.md) is cached, one
-cache file could conceivably be made up of several template files,
-config files, etc.
-
-Since templates are dynamic, it is important to be careful what you are
-caching and for how long. For instance, if you are displaying the front
-page of your website that does not change its content very often, it
-might work well to cache this page for an hour or more. On the other
-hand, if you are displaying a page with a timetable containing new
-information by the minute, it would not make sense to cache this page.
-
-## Table of contents
-- [Setting Up Caching](./caching/caching-setting-up.md)
-- [Multiple Caches Per Page](./caching/caching-multiple-caches.md)
-- [Controlling Cacheability of Output](./caching/caching-groups.md)
-- [Custom Cache Implementation](./caching/caching-custom.md)
diff --git a/docs/programmers/caching/caching-cacheable.md b/docs/programmers/caching/caching-cacheable.md
deleted file mode 100644
index 0fcba4b3..00000000
--- a/docs/programmers/caching/caching-cacheable.md
+++ /dev/null
@@ -1,128 +0,0 @@
-Controlling Cacheability of Output {#caching.cacheable}
-==================================
-
-If caching is enabled normally the whole final output of the page gets
-cached. However Smarty3 offers several options how to exclude sections
-of your output from caching.
-
-> **Note**
->
-> Be sure any variables used within a non-cached section are also
-> assigned from PHP when the page is loaded from the cache.
-
-Cacheability of Template Section {#cacheability.sections}
---------------------------------
-
-A larger section of your template can easily excluded from caching by
-using the [`{nocache}`](#language.function.nocache) and
-[`{/nocache}`](#language.function.nocache) tags.
-
-
-
-    Today's date is
-    {nocache}
-    {$smarty.now|date_format}
-    {/nocache}
-
-       
-
-The above code will output the current date on a cached page.
-
-Cacheability of Tags {#cacheability.tags}
---------------------
-
-Caching for an individual tag can be disabled by adding the \"nocache\"
-option flag to the tag.
-
-
-    Today's date is
-    {$smarty.now|date_format nocache}
-
-        
-
-Cacheability of Variables {#cacheability.variables}
--------------------------
-
-You can [`assign()`](#api.assign) variables as not cachable. Any tag
-which uses such variable will be automatically executed in nocache mode.
-
-> **Note**
->
-> If a tag is executed in nocache mode you must make sure that all other
-> variables used by that tag are also assigned from PHP when the page is
-> loaded from the cache.
-
-> **Note**
->
-> The nocache status of an assigned variable will effect the compiled
-> template code. If you change the status you must manually delete
-> existing compiled and cached template files to force a recompile.
-
-
-    // assign $foo as nocahe variable
-    $smarty->assign('foo',time(),true);
-
-
-    Dynamic time value is {$foo}
-
-        
-
-Cacheability of Plugins {#cacheability.plugins}
------------------------
-
-The cacheability of plugins can be declared when registering them. The
-third parameter to [`registerPlugin()`](#api.register.plugin) is called
-`$cacheable` and defaults to TRUE.
-
-When registering a plugin with `$cacheable=false` the plugin is called
-everytime the page is displayed, even if the page comes from the cache.
-
-> **Note**
->
-> The `$cacheable` status will affect the compiled template code. If you
-> change the status you must manually delete existing compiled and
-> cached template files to force a recompile.
-
-Example `index.php`:
-
-    <?php
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    function smarty_block_dynamic($param, $content, $smarty) {
-        return $content;
-    }
-    $smarty->registerPlugin('block','dynamic', 'smarty_block_dynamic', false);
-
-    $smarty->display('index.tpl');
-    ?>
-
-       
-
-where `index.tpl` is:
-
-
-    Page created: {'0'|date_format:'%D %H:%M:%S'}
-
-    {dynamic}
-
-    Now is: {'0'|date_format:'%D %H:%M:%S'}
-
-    ... do other stuff ...
-
-    {/dynamic}
-
-       
-
-When reloading the page you will notice that both dates differ. One is
-"dynamic" one is "static". You can do everything between
-`{dynamic}...{/dynamic}` and be sure it will not be cached like the rest
-of the page.
-
-> **Note**
->
-> The above example shall just demonstrate how a dynamic block plugins
-> works. See
-> [`Cacheability of Template Section`](#cacheability.sections) on how to
-> disable caching of a template section by the built-in
-> [`{nocache}`](#language.function.nocache) and
-> [`{/nocache}`](#language.function.nocache) tags.
diff --git a/docs/programmers/caching/caching-custom.md b/docs/programmers/caching/caching-custom.md
deleted file mode 100644
index b53afcfd..00000000
--- a/docs/programmers/caching/caching-custom.md
+++ /dev/null
@@ -1,296 +0,0 @@
-Custom Cache Implementation {#caching.custom}
-===========================
-
-As an alternative to using the default file-based caching mechanism, you
-can specify a custom cache implementation that will be used to read,
-write and clear cached files.
-
-> **Note**
->
-> In Smarty2 this used to be a callback function called
-> `$cache_handler_func`. Smarty3 replaced this callback by the
-> `Smarty_CacheResource` module.
-
-With a custom cache implementation you\'re likely trying to achieve at
-least one of the following goals: replace the slow filesystem by a
-faster storage engine, centralize the cache to be accessible to multiple
-servers.
-
-Smarty allows CacheResource implementations to use one of the APIs
-`\Smarty\Cacheresource\Custom` or `\Smarty\Cacheresource\KeyValueStore`.
-`\Smarty\Cacheresource\Custom` is a simple API directing all read, write,
-clear calls to your implementation. This API allows you to store
-wherever and however you deem fit. The
-`\Smarty\Cacheresource\KeyValueStore` API allows you to turn any \"dumb\"
-KeyValue-Store (like APC, Memcache, ...) into a full-featured
-CacheResource implementation. That is, everything around deep
-cache-groups like \"a\|b\|c\" is being handled for you in way that
-allows clearing the cache-group \"a\" and all nested groups are cleared
-as well - even though KeyValue-Stores don\'t allow this kind of
-hierarchy by nature.
-
-Custom CacheResources may be put in a file `cacheresource.foobarxyz.php`
-within your [`$plugins_dir`](#variable.plugins.dir), or registered on
-runtime with [`registerCacheResource()`](#api.register.cacheresource).
-In either case you need to set [`$caching_type`](#variable.caching.type)
-to invoke your custom CacheResource implementation.
-
-
-    <?php
-
-    use Smarty\Smarty;
-    $smarty = new Smarty();
-    $smarty->caching_type = 'mysql';
-
-    /**
-     * MySQL CacheResource
-     *
-     * CacheResource Implementation based on the Custom API to use
-     * MySQL as the storage resource for Smarty's output caching.
-     *
-     * Table definition:
-     * <pre>CREATE TABLE IF NOT EXISTS `output_cache` (
-     *   `id` CHAR(40) NOT NULL COMMENT 'sha1 hash',
-     *   `name` VARCHAR(250) NOT NULL,
-     *   `cache_id` VARCHAR(250) NULL DEFAULT NULL,
-     *   `compile_id` VARCHAR(250) NULL DEFAULT NULL,
-     *   `modified` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-     *   `content` LONGTEXT NOT NULL,
-     *   PRIMARY KEY (`id`),
-     *   INDEX(`name`),
-     *   INDEX(`cache_id`),
-     *   INDEX(`compile_id`),
-     *   INDEX(`modified`)
-     * ) ENGINE = InnoDB;</pre>
-     *
-    
-     * @author Rodney Rehm
-     */
-    class My_CacheResource_Mysql extends \Smarty\Cacheresource\Custom {
-        // PDO instance
-        protected $db;
-        protected $fetch;
-        protected $fetchTimestamp;
-        protected $save;
-        
-        public function __construct() {
-            try {
-                $this->db = new PDO("mysql:dbname=test;host=127.0.0.1", "smarty", "smarty");
-            } catch (PDOException $e) {
-                throw new \Smarty\Exception('Mysql Resource failed: ' . $e->getMessage());
-            }
-            $this->fetch = $this->db->prepare('SELECT modified, content FROM output_cache WHERE id = :id');
-            $this->fetchTimestamp = $this->db->prepare('SELECT modified FROM output_cache WHERE id = :id');
-            $this->save = $this->db->prepare('REPLACE INTO output_cache (id, name, cache_id, compile_id, content)
-                VALUES  (:id, :name, :cache_id, :compile_id, :content)');
-        }
-
-        /**
-         * fetch cached content and its modification time from data source
-         *
-         * @param string $id unique cache content identifier
-         * @param string $name template name
-         * @param string $cache_id cache id
-         * @param string $compile_id compile id
-         * @param string $content cached content
-         * @param integer $mtime cache modification timestamp (epoch)
-         * @return void
-         */
-        protected function fetch($id, $name, $cache_id, $compile_id, &$content, &$mtime)
-        {
-            $this->fetch->execute(array('id' => $id));
-            $row = $this->fetch->fetch();
-            $this->fetch->closeCursor();        
-            if ($row) {
-                $content = $row['content'];
-                $mtime = strtotime($row['modified']);
-            } else {
-                $content = null;
-                $mtime = null;
-            }
-        }
-        
-        /**
-         * Fetch cached content's modification timestamp from data source
-         *
-         * @note implementing this method is optional. Only implement it if modification times can be accessed faster than loading the complete cached content.
-         * @param string $id unique cache content identifier
-         * @param string $name template name
-         * @param string $cache_id cache id
-         * @param string $compile_id compile id
-         * @return integer|boolean timestamp (epoch) the template was modified, or false if not found
-         */
-        protected function fetchTimestamp($id, $name, $cache_id, $compile_id)
-        {
-            $this->fetchTimestamp->execute(array('id' => $id));
-            $mtime = strtotime($this->fetchTimestamp->fetchColumn());
-            $this->fetchTimestamp->closeCursor();
-            return $mtime;
-        }
-        
-        /**
-         * Save content to cache
-         *
-         * @param string $id unique cache content identifier
-         * @param string $name template name
-         * @param string $cache_id cache id
-         * @param string $compile_id compile id
-         * @param integer|null $exp_time seconds till expiration time in seconds or null
-         * @param string $content content to cache
-         * @return boolean success
-         */
-        protected function save($id, $name, $cache_id, $compile_id, $exp_time, $content)
-        {
-            $this->save->execute(array(
-                'id' => $id,
-                'name' => $name,
-                'cache_id' => $cache_id,
-                'compile_id' => $compile_id,
-                'content' => $content,
-            ));
-            return !!$this->save->rowCount();
-        }
-        
-        /**
-         * Delete content from cache
-         *
-         * @param string $name template name
-         * @param string $cache_id cache id
-         * @param string $compile_id compile id
-         * @param integer|null $exp_time seconds till expiration or null
-         * @return integer number of deleted caches
-         */
-        protected function delete($name, $cache_id, $compile_id, $exp_time)
-        {
-            // delete the whole cache
-            if ($name === null && $cache_id === null && $compile_id === null && $exp_time === null) {
-                // returning the number of deleted caches would require a second query to count them
-                $query = $this->db->query('TRUNCATE TABLE output_cache');
-                return -1;
-            }
-            // build the filter
-            $where = array();
-            // equal test name
-            if ($name !== null) {
-                $where[] = 'name = ' . $this->db->quote($name);
-            }
-            // equal test compile_id
-            if ($compile_id !== null) {
-                $where[] = 'compile_id = ' . $this->db->quote($compile_id);
-            }
-            // range test expiration time
-            if ($exp_time !== null) {
-                $where[] = 'modified < DATE_SUB(NOW(), INTERVAL ' . intval($exp_time) . ' SECOND)';
-            }
-            // equal test cache_id and match sub-groups
-            if ($cache_id !== null) {
-                $where[] = '(cache_id = '. $this->db->quote($cache_id)
-                    . ' OR cache_id LIKE '. $this->db->quote($cache_id .'|%') .')';
-            }
-            // run delete query
-            $query = $this->db->query('DELETE FROM output_cache WHERE ' . join(' AND ', $where));
-            return $query->rowCount();
-        }
-    }
-
-       
-
-
-    <?php
-
-    use Smarty\Smarty;
-    $smarty = new Smarty();
-    $smarty->caching_type = 'memcache';
-
-    /**
-     * Memcache CacheResource
-     *
-     * CacheResource Implementation based on the KeyValueStore API to use
-     * memcache as the storage resource for Smarty's output caching.
-     *
-     * Note that memcache has a limitation of 256 characters per cache-key.
-     * To avoid complications all cache-keys are translated to a sha1 hash.
-     *
-    
-     * @author Rodney Rehm
-     */
-    class My_CacheResource_Memcache extends \Smarty\Cacheresource\KeyValueStore {
-        /**
-         * memcache instance
-         * @var Memcache
-         */
-        protected $memcache = null;
-        
-        public function __construct()
-        {
-            $this->memcache = new Memcache();
-            $this->memcache->addServer( '127.0.0.1', 11211 );
-        }
-        
-        /**
-         * Read values for a set of keys from cache
-         *
-         * @param array $keys list of keys to fetch
-         * @return array list of values with the given keys used as indexes
-         * @return boolean true on success, false on failure
-         */
-        protected function read(array $keys)
-        {
-            $_keys = $lookup = array();
-            foreach ($keys as $k) {
-                $_k = sha1($k);
-                $_keys[] = $_k;
-                $lookup[$_k] = $k;
-            }
-            $_res = array();
-            $res = $this->memcache->get($_keys);
-            foreach ($res as $k => $v) {
-                $_res[$lookup[$k]] = $v;
-            }
-            return $_res;
-        }
-        
-        /**
-         * Save values for a set of keys to cache
-         *
-         * @param array $keys list of values to save
-         * @param int $expire expiration time
-         * @return boolean true on success, false on failure
-         */
-        protected function write(array $keys, $expire=null)
-        {
-            foreach ($keys as $k => $v) {
-                $k = sha1($k);
-                $this->memcache->set($k, $v, 0, $expire);
-            }
-            return true;
-        }
-
-        /**
-         * Remove values from cache
-         *
-         * @param array $keys list of keys to delete
-         * @return boolean true on success, false on failure
-         */
-        protected function delete(array $keys)
-        {
-            foreach ($keys as $k) {
-                $k = sha1($k);
-                $this->memcache->delete($k);
-            }
-            return true;
-        }
-
-        /**
-         * Remove *all* values from cache
-         *
-         * @return boolean true on success, false on failure
-         */
-        protected function purge()
-        {
-            return $this->memcache->flush();
-        }
-    }
-
-
-       
diff --git a/docs/programmers/caching/caching-groups.md b/docs/programmers/caching/caching-groups.md
deleted file mode 100644
index a3502f3f..00000000
--- a/docs/programmers/caching/caching-groups.md
+++ /dev/null
@@ -1,60 +0,0 @@
-Cache Groups {#caching.groups}
-============
-
-You can do more elaborate grouping by setting up `$cache_id` groups.
-This is accomplished by separating each sub-group with a vertical bar
-`|` in the `$cache_id` value. You can have as many sub-groups as you
-like.
-
--   You can think of cache groups like a directory hierarchy. For
-    instance, a cache group of `'a|b|c'` could be thought of as the
-    directory structure `'/a/b/c/'`.
-
--   `clearCache(null,'a|b|c')` would be like removing the files
-    `'/a/b/c/*'`. `clearCache(null,'a|b')` would be like removing the
-    files `'/a/b/*'`.
-
--   If you specify a [`$compile_id`](#variable.compile.id) such as
-    `clearCache(null,'a|b','foo')` it is treated as an appended cache
-    group `'/a/b/c/foo/'`.
-
--   If you specify a template name such as
-    `clearCache('foo.tpl','a|b|c')` then Smarty will attempt to remove
-    `'/a/b/c/foo.tpl'`.
-
--   You CANNOT remove a specified template name under multiple cache
-    groups such as `'/a/b/*/foo.tpl'`, the cache grouping works
-    left-to-right ONLY. You will need to group your templates under a
-    single cache group hierarchy to be able to clear them as a group.
-
-Cache grouping should not be confused with your template directory
-hierarchy, the cache grouping has no knowledge of how your templates are
-structured. So for example, if you have a template structure like
-`themes/blue/index.tpl` and you want to be able to clear all the cache
-files for the "blue" theme, you will need to create a cache group
-structure that mimics your template file structure, such as
-`display('themes/blue/index.tpl','themes|blue')`, then clear them with
-`clearCache(null,'themes|blue')`.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    // clear all caches with 'sports|basketball' as the first two cache_id groups
-    $smarty->clearCache(null,'sports|basketball');
-
-    // clear all caches with "sports" as the first cache_id group. This would
-    // include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
-    $smarty->clearCache(null,'sports');
-
-    // clear the foo.tpl cache file with "sports|basketball" as the cache_id
-    $smarty->clearCache('foo.tpl','sports|basketball');
-
-
-    $smarty->display('index.tpl','sports|basketball');
-    ?>
-
-          
diff --git a/docs/programmers/caching/caching-multiple-caches.md b/docs/programmers/caching/caching-multiple-caches.md
deleted file mode 100644
index a25e442c..00000000
--- a/docs/programmers/caching/caching-multiple-caches.md
+++ /dev/null
@@ -1,87 +0,0 @@
-Multiple Caches Per Page {#caching.multiple.caches}
-========================
-
-You can have multiple cache files for a single call to
-[`display()`](#api.display) or [`fetch()`](#api.fetch). Let\'s say that
-a call to `display('index.tpl')` may have several different output
-contents depending on some condition, and you want separate caches for
-each one. You can do this by passing a `$cache_id` as the second
-parameter to the function call.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    $my_cache_id = $_GET['article_id'];
-
-    $smarty->display('index.tpl', $my_cache_id);
-    ?>
-
-         
-
-Above, we are passing the variable `$my_cache_id` to
-[`display()`](#api.display) as the `$cache_id`. For each unique value of
-`$my_cache_id`, a separate cache will be generated for `index.tpl`. In
-this example, `article_id` was passed in the URL and is used as the
-`$cache_id`.
-
-> **Note**
->
-> Be very cautious when passing values from a client (web browser) into
-> Smarty or any PHP application. Although the above example of using the
-> article\_id from the URL looks handy, it could have bad consequences.
-> The `$cache_id` is used to create a directory on the file system, so
-> if the user decided to pass an extremely large value for article\_id,
-> or write a script that sends random article\_id\'s at a rapid pace,
-> this could possibly cause problems at the server level. Be sure to
-> sanitize any data passed in before using it. In this instance, maybe
-> you know the article\_id has a length of ten characters and is made up
-> of alpha-numerics only, and must be a valid article\_id in the
-> database. Check for this!
-
-Be sure to pass the same `$cache_id` as the second parameter to
-[`isCached()`](#api.is.cached) and [`clearCache()`](#api.clear.cache).
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    $my_cache_id = $_GET['article_id'];
-
-    if(!$smarty->isCached('index.tpl',$my_cache_id)) {
-        // No cache available, do variable assignments here.
-        $contents = get_database_contents();
-        $smarty->assign($contents);
-    }
-
-    $smarty->display('index.tpl',$my_cache_id);
-    ?>
-
-         
-
-You can clear all caches for a particular `$cache_id` by passing NULL as
-the first parameter to [`clearCache()`](#api.clear.cache).
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    // clear all caches with "sports" as the $cache_id
-    $smarty->clearCache(null,'sports');
-
-    $smarty->display('index.tpl','sports');
-    ?>
-
-         
-
-In this manner, you can "group" your caches together by giving them the
-same `$cache_id`.
diff --git a/docs/programmers/caching/caching-setting-up.md b/docs/programmers/caching/caching-setting-up.md
deleted file mode 100644
index 189c7cd3..00000000
--- a/docs/programmers/caching/caching-setting-up.md
+++ /dev/null
@@ -1,150 +0,0 @@
-Setting Up Caching {#caching.setting.up}
-==================
-
-The first thing to do is enable caching by setting
-[`$caching`](#variable.caching) to one of
-`\Smarty\Smarty::CACHING_LIFETIME_CURRENT` or `Smarty::CACHING_LIFETIME_SAVED`.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    // uses the value of $smarty->cacheLifetime() to determine
-    // the number of seconds a cache is good for
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    $smarty->display('index.tpl');
-    ?>
-
-        
-
-With caching enabled, the function call to `display('index.tpl')` will
-render the template as usual, but also saves a copy of its output to a
-file (a cached copy) in the [`$cache_dir`](#variable.cache.dir). On the
-next call to `display('index.tpl')`, the cached copy will be used
-instead of rendering the template again.
-
-> **Note**
->
-> The files in the [`$cache_dir`](#variable.cache.dir) are named similar
-> to the template name. Although they end in the `.php` extension, they
-> are not intended to be directly executable. Do not edit these files!
-
-Each cached page has a limited lifetime determined by
-[`$cache_lifetime`](#variable.cache.lifetime). The default value is 3600
-seconds, or one hour. After that time expires, the cache is regenerated.
-It is possible to give individual caches their own expiration time by
-setting [`$caching`](#variable.caching) to
-`\Smarty\Smarty::CACHING_LIFETIME_SAVED`. See
-[`$cache_lifetime`](#variable.cache.lifetime) for more details.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    // retain current cache lifetime for each specific display call
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_SAVED);
-
-    // set the cache_lifetime for index.tpl to 5 minutes
-    $smarty->setCacheLifetime(300);
-    $smarty->display('index.tpl');
-
-    // set the cache_lifetime for home.tpl to 1 hour
-    $smarty->setCacheLifetime(3600);
-    $smarty->display('home.tpl');
-
-    // NOTE: the following $cache_lifetime setting will not work when $caching
-    // is set to Smarty::CACHING_LIFETIME_SAVED.
-    // The cache lifetime for home.tpl has already been set
-    // to 1 hour, and will no longer respect the value of $cache_lifetime.
-    // The home.tpl cache will still expire after 1 hour.
-    $smarty->setCacheLifetime(30); // 30 seconds
-    $smarty->display('home.tpl');
-    ?>
-
-        
-
-If [`$compile_check`](#variable.compile.check) is enabled (default),
-every template file and config file that is involved with the cache file
-is checked for modification. If any of the files have been modified
-since the cache was generated, the cache is immediately regenerated.
-This is a computational overhead, so for optimum performance set
-[`$compile_check`](#variable.compile.check) to FALSE.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-    $smarty->setCompileCheck(false);
-
-    $smarty->display('index.tpl');
-    ?>
-
-        
-
-If [`$force_compile`](#variable.force.compile) is enabled, the cache
-files will always be regenerated. This effectively disables caching,
-however this also seriously degrades performance.
-[`$force_compile`](#variable.force.compile) is meant to be used for
-[debugging](#chapter.debugging.console) purposes. The appropriate way to
-disable caching is to set [`$caching`](#variable.caching) to
-\Smarty\Smarty::CACHING\_OFF.
-
-The [`isCached()`](#api.is.cached) function can be used to test if a
-template has a valid cache or not. If you have a cached template that
-requires something like a database fetch, you can use this to skip that
-process.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    if(!$smarty->isCached('index.tpl')) {
-        // No cache available, do variable assignments here.
-        $contents = get_database_contents();
-        $smarty->assign($contents);
-    }
-
-    $smarty->display('index.tpl');
-    ?>
-
-        
-
-You can keep parts of a page dynamic (disable caching) with the
-[`{nocache}{/nocache}`](#language.function.nocache) block function, or by using the
-`nocache` parameter for most template functions.
-
-Let\'s say the whole page can be cached except for a banner that is
-displayed down the side of the page. By using a [`{nocache}{/nocache}`](#language.function.nocache)
-block for the banner, you can
-keep this element dynamic within the cached content.
-
-You can clear all the cache files with the
-[`clearAllCache()`](#api.clear.all.cache) function, or individual cache
-files [and groups](#caching.groups) with the
-[`clearCache()`](#api.clear.cache) function.
-
-
-    <?php
-    use Smarty\Smarty;
-    $smarty = new Smarty;
-
-    $smarty->setCaching(Smarty::CACHING_LIFETIME_CURRENT);
-
-    // clear only cache for index.tpl
-    $smarty->clearCache('index.tpl');
-
-    // clear out all cache files
-    $smarty->clearAllCache();
-
-    $smarty->display('index.tpl');
-    ?>
-
-        
diff --git a/mkdocs.yml b/mkdocs.yml
index 239bd360..abed5d8b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -130,7 +130,7 @@ nav:
       - 'Template resources': 'api/resources.md'
       - 'Caching':
         - 'Basics': 'api/caching/basics.md'
-        - 'Multiple caches per page': 'api/caching/multiple-caches-per-pages.md'
+        - 'Multiple caches per template': 'api/caching/multiple-caches-per-template.md'
         - 'Custom cache storage layers': 'api/caching/custom-storage-layers.md'
       - 'Extending Smarty':
           - 'Introduction': 'api/extending/introduction.md'