Reviewed documentation for publication

- Checked all headers (fixes #30)
- Checked all tables (fixes #33)
- Checked all blockquotes (fixes #34)
- Checked for content and examples (fixes #32)

This patch also converts to mkdocs, and reorganizes the structure slightly.

.gitignore

@@ -6,7 +6,9 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock

README.md

@@ -9,4 +9,4 @@ storage adapters (DB, File, Memcache, etc).
 
 
 - File issues at https://github.com/zendframework/zend-cache/issues
-- Documentation is at http://framework.zend.com/manual/current/en/index.html#zend-cache
+- Documentation is at https://zendframework.github.io/zend-cache/

doc/book/index.html

@@ -0,0 +1,11 @@
+<div class="container">
+  <div class="jumbotron">
+    <h1>zend-cache</h1>
+
+    <p>Caching implementation with a variety of storage options, as well as
+      codified caching strategies for callbacks, classes, and output.</p>
+
+    <pre><code class="language-bash">$ composer require zendframework/zend-cache</code></pre>
+  </div>
+</div>
+

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/pattern/callback-cache.md

@@ -0,0 +1,92 @@
+# CallbackCache
+
+
+The callback cache pattern caches the results of arbitrary PHP callables.
+
+## Quick Start
+
+```php
+use Zend\Cache\PatternFactory;
+use Zend\Cache\Pattern\PatternOptions;
+
+// Via the factory:
+$callbackCache = PatternFactory::factory('callback', [
+    'storage'      => 'apc',
+    'cache_output' => true,
+]);
+
+// Or the equivalent manual instantiation:
+$callbackCache = new \Zend\Cache\Pattern\CallbackCache();
+$callbackCache->setOptions(new PatternOptions([
+    'storage'      => 'apc',
+    'cache_output' => true,
+]));
+```
+
+## Configuration Options
+
+Option | Data Type | Default Value | Description
+------ | --------- | ------------- | -----------
+`storage` | `string | array | Zend\Cache\Storage\StorageInterface` | none | Adapter used for reading and writing cached data.
+`cache_output` | `boolean` | `true` | Whether or not to cache callback output.
+
+## Available Methods
+
+In addition to the methods defined in the `PatternInterface`, this
+implementation provides the following methods.
+
+```php
+namespace Zend\Cache\Pattern;
+
+use Zend\Cache\Exception;
+use Zend\Stdlib\ErrorHandler;
+
+class CallbackCache extends AbstractPattern
+{
+    /**
+     * Call the specified callback or get the result from cache
+     *
+     * @param  callable   $callback  A valid callback
+     * @param  array      $args      Callback arguments
+     * @return mixed Result
+     * @throws Exception\RuntimeException if invalid cached data
+     * @throws \Exception
+     */
+    public function call($callback, array $args = []);
+
+    /**
+     * Intercept method overloading; proxies to call()
+     *
+     * @param  string $function  Function name to call
+     * @param  array  $args      Function arguments
+     * @return mixed
+     * @throws Exception\RuntimeException
+     * @throws \Exception
+     */
+    public function __call($function, array $args);
+
+    /**
+     * Generate a unique key in base of a key representing the callback part
+     * and a key representing the arguments part.
+     *
+     * @param  callable   $callback  A valid callback
+     * @param  array      $args      Callback arguments
+     * @return string
+     * @throws Exception\RuntimeException
+     * @throws Exception\InvalidArgumentException
+     */
+    public function generateKey($callback, array $args = []);
+}
+```
+
+## Examples
+
+### Instantiating the callback cache pattern
+
+```php
+use Zend\Cache\PatternFactory;
+
+$callbackCache = PatternFactory::factory('callback', [
+    'storage' => 'apc'
+]);
+```

doc/book/pattern/capture-cache.md

@@ -0,0 +1,145 @@
+# CaptureCache
+
+The `CaptureCache` pattern is useful for generating static resources to return
+via HTTP request. When used in such a fashion, the web server needs to be
+configured to run a PHP script generating the requested resource so that
+subsequent requests for the same resource can be shipped without calling PHP
+again.
+
+This pattern comes with basic logic for managing generated resources.
+
+## Quick Start
+
+For use with an Apache 404 handler:
+
+```apacheconf
+# .htdocs
+ErrorDocument 404 /index.php
+```
+
+```php
+// index.php
+use Zend\Cache\PatternFactory;
+$capture = Zend\Cache\PatternFactory::factory('capture', [
+    'public_dir' => __DIR__,
+]);
+
+// Start capturing all output, excluding headers, and write to the public
+// directory:
+$capture->start();
+
+// Don't forget to change the HTTP response code
+header('Status: 200', true, 200);
+
+// do stuff to dynamically generate output
+```
+
+## Configuration Options
+
+Option | Data Type | Default Value | Description
+------ | --------- | ------------- | -----------
+`public_dir` | `string` | none | Location of the public web root directory in which to write output.
+`index_filename` | `string` | "index.html" | The name of the index file if only a directory was requested.
+`file_locking` | `bool` | `true` | Whether or not to lock output files when writing.
+`file_permission` | `int | bool` | `0600` (`false` on Windows) | Default permissions for generated output files.
+`dir_permission` | `int | bool` | `0700` (`false` on Windows) | Default permissions for generated output directories.
+`umask` | `int` | `bool` | `false` | Whether or not to umask generated output files / directories.
+
+## Available Methods
+
+In addition to the methods exposed in `PatternInterface`, this implementation
+exposes the following methods.
+
+```php
+namespace Zend\Cache\Pattern;
+
+use Zend\Cache\Exception;
+use Zend\Stdlib\ErrorHandler;
+
+class CaptureCache extends AbstractPattern
+{
+    /**
+     * Start the cache.
+     *
+     * @param  string $pageId  Page identifier
+     * @return void
+     */
+    public function start($pageId = null);
+
+    /**
+     * Write a page to the requested path.
+     *
+     * @param string      $content
+     * @param null|string $pageId
+     * @throws Exception\LogicException
+     */
+    public function set($content, $pageId = null);
+
+    /**
+     * Retrieve a generated page from the cache.
+     *
+     * @param  null|string $pageId
+     * @return string|null
+     * @throws Exception\LogicException
+     * @throws Exception\RuntimeException
+     */
+    public function get($pageId = null);
+
+    /**
+     * Check if a cache exists for the given page.
+     *
+     * @param  null|string $pageId
+     * @throws Exception\LogicException
+     * @return bool
+     */
+    public function has($pageId = null);
+
+    /**
+     * Remove a page from the cache.
+     *
+     * @param  null|string $pageId
+     * @throws Exception\LogicException
+     * @throws Exception\RuntimeException
+     * @return bool
+     */
+    public function remove($pageId = null);
+
+    /**
+     * Clear cached pages that match the specified glob pattern.
+     *
+     * @param string $pattern
+     * @throws Exception\LogicException
+     */
+    public function clearByGlob($pattern = '**');
+
+    /**
+     * Returns the generated file name.
+     *
+     * @param null|string $pageId
+     * @return string
+     */
+    public function getFilename($pageId = null);
+}
+```
+
+## Examples
+
+### Scaling images in the web root
+
+Using the following Apache 404 configuration:
+
+```apacheconf
+# .htdocs
+ErrorDocument 404 /index.php
+```
+
+Use the following script:
+
+```php
+// index.php
+$captureCache = Zend\Cache\PatternFactory::factory('capture', [
+    'public_dir' => __DIR__,
+]);
+
+// TODO
+```