Documentation polishing

- [X] What is PSR-7?
- [X] What is middleware?
- [X] What can you build with Expressive?
- [X] Features of Expressive
    - Routing
        - path-based
        - HTTP method constraints (405 responses built-in)
        - abstractions
    - container-interop
        - lazy-loading routed middleware
        - lazy-loading *piped* middleware
    - Error handling
        - basic 404 and general errors
        - templated error pages
        - whoops for development
    - Templating
        - abstracted
        - namespaced templates
        - layouts can be assumed
- [X] Routing
    - [X] Detail how to fetch the matched attributes!
    - [X] Show simplified router factories when showing containers.
      Most of the routers do not *need* a factory, unless the user wants to
      provide additional configuration. As such, invokables or closures that
      return the instance will suffice in most cases. Have separate sections
      on *advanced* factories.
- [X] Emitters and the EmitterStack
- [X] Use case examples
    - Make them follow the guidelines from the various container examples with
      regards to configuration/service definition location.
- [X] Search for "zend-expressive" at the start of sentences, and replace with "Expressive".

Author: weierophinney

doc/book/application.md

@@ -14,8 +14,8 @@ that composes:
 
 You can define the `Application` instance in several ways:
 
-- Direct instantiation (which requires providing several dependencies).
-- The `AppFactory` (which will use sane defaults, but allows injecting alternate
+- Direct instantiation, which requires providing several dependencies.
+- The `AppFactory`, which will use sane defaults, but allows injecting alternate
   container and/or router implementations.
 - Via a dependency injection container; we provide a factory for setting up all
   aspects of the instance via configuration and other defined services.
@@ -50,6 +50,9 @@ public function __construct(
 );
 ```
 
+If no container is provided at instantiation, then all routed and piped
+middleware **must** be provided as callables.
+
 ### AppFactory
 
 `Zend\Expressive\AppFactory` provides a convenience layer for creating an
@@ -64,6 +67,11 @@ AppFactory::create(
 );
 ```
 
+When no container or router are provided, it defaults to:
+
+- zend-servicemanager for the container.
+- Aura.Router for the router.
+
 ### Container factory
 
 We also provide a factory that can be consumed by a
@@ -114,7 +122,7 @@ Each of the methods `get()`, `post()`, `put()`, `patch()`, and `delete()`
 proxies to `route()` and has the signature:
 
 ```php
-public function route(
+function (
     $pathOrRoute,
     $middleware = null,
     $name = null
@@ -175,11 +183,14 @@ Routing is accomplished via dedicated a dedicated middleware method,
 `Application::routeMiddleware()`. It is an instance method, and can be
 piped/registered with other middleware platforms if desired.
 
-Internally, any time `route()` is called (including via one of the proxy
-methods), or during `__invoke()` (the exposed application middleware), the
-instance will call `pipeRoutingMiddleware()`, which will pipe
-`Application::routeMiddleware` to the middleware pipeline. You can also pipe it
-manually if desired.
+Internally, the first time `route()` is called (including via one of the proxy
+methods), or, if never called, when `__invoke()` (the exposed application
+middleware) is called, the instance will pipe `Application::routeMiddleware` to
+the middleware pipeline. You can also pipe it manually if desired:
+
+```php
+$app->pipeRoutingMiddleware();
+```
 
 ## Retrieving dependencies
 

doc/book/container/factories.md

@@ -1,6 +1,6 @@
 # Provided Factories
 
-zend-expressive provides several factories compatible with container-interop to
+Expressive provides several factories compatible with container-interop to
 facilitate setting up common dependencies. The following is a list of provided
 containers, what they will create, the suggested service name, and any
 additional dependencies they may require.

doc/book/container/intro.md

@@ -1,7 +1,8 @@
 # Containers
 
-zend-expressive promotes and advocates the usage of
+Expressive promotes and advocates the usage of
 [Dependency Injection](http://www.martinfowler.com/articles/injection.html)/[Inversion of Control](https://en.wikipedia.org/wiki/Inversion_of_control)
+(also referred to as DI — or DIC — and IoC, respectively)
 containers when writing your applications. These should be used for the
 following:
 
@@ -21,10 +22,8 @@ examples.
 
 At this time, we document support for the following specific containers:
 
-- [zend-servicemanager](https://github.com/zendframework/zend-servicemanager):
-  `composer require zendframework/zend-servicemanager`
-- [pimple-interop](https://github.com/moufmouf/pimple-interop):
-  `composer require mouf/pimple-interop`
+- [zend-servicemanager](zend-servicemanager.md)
+- [pimple-interop](pimple.md)
 
 > ## Service Names
 >

doc/book/cookbook.md

@@ -22,7 +22,10 @@ Let's assume the above represents an API.
 As your application progresses, you may have a mixture of different content, and now want to have
 the above segregated under the path `/api`.
 
-To do that:
+This is essentially the same problem as addressed in the
+["Segregating your application to a subpath"](usage-examples.md#segregating-your-application-to-a-subpath] example.
+
+To accomplish it:
 
 - Create a new application.
 - Pipe the previous application to the new one, under the path `/api`.
@@ -41,6 +44,6 @@ $app->pipe('/api', $api);
 $app->run();
 ```
 
-The above works, because ever `Application` instance is itself middleware, and, more specifically,
+The above works, because every `Application` instance is itself middleware, and, more specifically,
 an instance of [Stratigility's `MiddlewarePipe`](https://github.com/zendframework/zend-stratigility/blob/master/doc/book/middleware.md),
 which provides the ability to compose middleware.

doc/book/emitters.md

@@ -0,0 +1,41 @@
+# Emitters
+
+To simplify the usage of Expressive, we added the `run()` method, which handles
+the incoming request, and emits a response.
+
+The latter aspect, emitting the response, is the responsibility of an
+[emitter](https://github.com/zendframework/zend-diactoros/blob/master/doc/book/emitting-responses.md).
+An emitter accepts a response instance, and then does something with it, usually
+sending the response back to a browser.
+
+Diactoros defines an `EmitterInterface`, and — as of the time we write this — a
+single emitter implementation, `Zend\Diactoros\Response\SapiEmitter`, which
+sends headers and output using PHP's standard SAPI mechanisms (the `header()`
+method and the output buffer).
+
+We recognize that there are times when you may want to use alternate emitter
+implementations; for example, if you use [React](http://reactphp.org), the SAPI
+emitter will likely not work for you.
+
+To facilitate alternate emitters, we offer two facilities:
+
+- First, `Application` composes an emitter, and you can specify an alternate
+  emitter during instantiation, or via the `Zend\Diactoros\Response\EmitterInterface`
+  service when using the container factory.
+- Second, we provide `Zend\Expressive\Emitter\EmitterStack`, which allows you to
+  compose multiple emitter strategies; the first to return a value other than
+  boolean `false` will cause execution of the stack to short-circuit.
+  `Application` composes an `EmitterStack` by default, with an `SapiEmitter`
+  composed at the bottom of the stack.
+
+## EmitterStack
+
+The `EmitterStack` is an `SplStack` extension that implements
+`EmitterInterface`. You can add emitters to the stack by pushing them on:
+
+```php
+$stack->push($emitterInstance);
+```
+
+As a stack, execution is in LIFO (last in, first out) order; the first emitter
+on the stack will be evaluated last.

doc/book/error-handling.md

@@ -1,6 +1,6 @@
 # Error Handling
 
-zend-expressive provides error handling out of the box, via zend-stratigility's [FinalHandler
+Expressive provides error handling out of the box, via zend-stratigility's [FinalHandler
 implementation](https://github.com/zendframework/zend-stratigility/blob/master/doc/book/api.md#finalhandler).
 This pseudo-middleware is executed in the following conditions:
 
@@ -38,7 +38,7 @@ optionally, a `Zend\Expressive\Template\TemplateInterface` instance, and templat
 404 and general error conditions. This makes it a good choice for use in production.
 
 First, of course, you'll need to select a templating system and ensure you have
-the appropriate dependencies installed; see the [templating documentation](../template/intro.md)
+the appropriate dependencies installed; see the [templating documentation](template/intro.md)
 for information on what we support and how to install supported systems.
 
 Once you have selected your templating system, you can setup the templated error
@@ -63,6 +63,9 @@ You can also use the `TemplatedErrorHandler` as a substitute for the `FinalHandl
 templated capabilities, by omitting the `TemplateInterface` instance when instantiating it. In this
 case, the response message bodies will be empty, though the response status will reflect the error.
 
+See the section titled "Container Factories and Configuration", below, for techniques on configuring
+the `TemplatedErrorHandler` as your final handler within a container-based application.
+
 ## Whoops
 
 [whoops](http://filp.github.io/whoops/) is a library for providing a more usable UI around
@@ -121,11 +124,17 @@ You can add more handlers if desired.
 Internally, when an exception is discovered, zend-expressive adds some data to the whoops output,
 primarily around the request information (URI, HTTP request method, route match attributes, etc.).
 
+See the next section for techniques on configuring the `WhoopsErrorHandler` as your final handler
+within a container-based application.
+
 ## Container Factories and Configuration
 
 The above may feel like a bit much when creating your application. As such, we provide several
 factories that work with [container-interop](https://github.com/container-interop/container-interop)-compatible
 container implementations to simplify setup.
 
-See the [container factory documentation](../container/factories.md) for
-details.
+In each case, you should register the selected error handler's factory as the service
+`Zend\Expressive\FinalHandler`.
+
+- For the `TemplatedErrorHandler`, use [`Zend\Expressive\Container\TemplatedErrorHandlerFactory`](container/factories.md#templatederrorhandlerfactory).
+- For the `WhoopsErrorHandler`, use [`Zend\Expressive\Container\WhoopsErrorHandlerFactory`](container/factories.md#whoopserrorhandlerfactory).

doc/book/features.md

@@ -0,0 +1,66 @@
+# Overview
+
+Expressive allows you to write [PSR-7](http://www.php-fig.org/psr/psr-7/)
+[middleware](https://github.com/zendframework/zend-stratigility/blob/master/doc/book/middleware.md)
+applications for the web.
+
+PSR-7 is a standard defining HTTP message interfaces; these are the incoming
+request and outgoing response for your application. By using PSR-7, we ensure
+that your applications will work in other PSR-7 contexts.
+
+Middleware is any code sitting between a request and a response; it typically
+analyzes the request to aggregate incoming data, delegates it to another layer
+to process, and then creates and returns a response. Middleware can and should
+be relegated only to those tasks, and should be relatively easy to write and
+maintain.
+
+Middleware is also designed for composability; you should be able to nest
+middleware and re-use middleware.
+
+With Expressive, you can build PSR-7-based middleware applications:
+
+- APIs
+- Websites
+- Single Page Applications
+- and more.
+
+## Features
+
+Expressive builds on [zend-stratigility](https://github.com/zendframework/zend-stratigility)
+to provide a robust convenience layer on which to build applications. The
+features it provides include:
+
+- **Routing**
+  
+  Stratigility provides limited, literal matching only. Expressive allows you
+  to utilize dynamic routing capabilities from a variety of routers, providing
+  much more fine-grained matching capabilities. The routing layer also allows
+  restricting matched routes to specific HTTP methods, and will return "405 Not
+  Allowed" responses with an "Allow" HTTP header containing allowed HTTP
+  methods for invalid requests.
+
+  Routing is abstracted in Expressive, allowing the developer to choose the
+  routing library that best fits the project needs. By default, we provide
+  wrappers for Aura.Router, FastRoute, and the zend-mvc router.
+
+- **contaienr-interop**
+
+  Expressive encourages the use of Dependency Injection, and defines its
+  `Application` class to compose a container-interop `ContainerInterface`
+  instance. The container is used to lazy-load middleware, whether it is
+  piped (Stratigility interface) or routed (Expressive).
+
+- **Templating**
+
+  While Expressive does not assume templating is being used, it provides a
+  templating abstraction. Developers can write middleware that typehints on
+  this abstraction, and assume that the underlying adapter will provide
+  layout support and namespaced template support.
+
+- **Error Handling**
+
+  Applications should handle errors gracefully, but also handle them differently
+  in development versus production. Expressive provides both basic error
+  handling via Stratigility's own `FinalHandler` implementation, as well as
+  more advanced error handling via two specialized error handlers: a templated
+  error handler for production, and a Whoops-based error handler for development.

doc/book/quick-start.md

@@ -1,8 +1,8 @@
 # Quick Start
 
-zend-expressive allows you to get started at your own pace. You can start with
+Expressive allows you to get started at your own pace. You can start with
 the simplest example, detailed below, or move on to a more structured,
-configuration-driven approach as detailed in the [use case examples](examples.md).
+configuration-driven approach as detailed in the [use case examples](usage-examples.md).
 
 ## 1. Create a new project directory
 

doc/book/router/aura.md

@@ -44,11 +44,23 @@ To use Aura.Router, you will first need to install it:
 $ composer require aura/router
 ```
 
+## Quick Start
+
+At its simplest, you can instantiate a `Zend\Expressive\Router\Aura` instance
+with no arguments; it will create the underlying Aura.Router objects required
+and compose them for you:
+
+```php
+use Zend\Expressive\Router\Aura;
+
+$router = new Aura();
+```
+
 ## Programmatic Creation
 
-To handle it programmatically, you will need to setup the Aura.Router instance
-manually, inject it into a `Zend\Expressive\Router\Aura` instance, and inject
-use that when creating your `Application` instance.
+If you need greater control over the Aura.Router setup and configuration, you
+can create the instances necessary and inject them into
+`Zend\Expressive\Router\Aura` during instantiation.
 
 ```php
 <?php
@@ -81,7 +93,65 @@ $app = AppFactory::create(null, $router);
 
 [We recommend using an Inversion of Control container](../container/intro.md)
 for your applications; as such, in this section we will demonstrate 
-defining two factories:
+two strategies for creating your Aura.Router implementation.
+
+### Basic Router
+
+If you don't need to provide any setup or configuration, you can simply
+instantiate and return an instance of `Zend\Expressive\Router\Aura` for the
+service name `Zend\Expressive\Router\RouterInterface`.
+
+A factory would look like this:
+
+```php
+// in src/Application/Container/RouterFactory.php
+namespace Application\Container;
+
+use Interop\Container\ContainerInterface;
+use Zend\Expressive\Router\Aura;
+
+class RouterFactory
+{
+    /**
+     * @param ContainerInterface $container
+     * @return Aura
+     */
+    public function __invoke(ContainerInterface $container)
+    {
+        return new Aura();
+    }
+}
+```
+
+You would register this with zend-servicemanager using:
+
+```php
+$container->setFactory(
+    'Zend\Expressive\Router\RouterInterface',
+    'Application\Container\RouterFactory'
+);
+```
+
+And in Pimple:
+
+```php
+$pimple['Zend\Expressive\Router\RouterInterface'] = new Application\Container\RouterFactory();
+```
+
+For zend-servicemanager, you can omit the factory entirely, and register the
+class as an invokable:
+
+```php
+$container->setInvokableClass(
+    'Zend\Expressive\Router\RouterInterface',
+    'Zend\Expressive\Router\Aura'
+);
+```
+
+### Advanced Configuration
+
+If you want to provide custom setup or configuration, you can do so. In this
+example, we will be defining two factories:
 
 - A factory to register as and generate an `Aura\Router\Router` instance.
 - A factory registered as `Zend\Expressive\Router\RouterInterface`, which