doc: style fixes

docs/source/concepts/interfaces.rst

@@ -4,13 +4,14 @@
 `kapow server` sets up three HTTP server interfaces, each with a distinct and
 clear purpose.
 
+
 User Interface
 --------------
 
 The User HTTP interface is used to serve final user requests.
 
-By default it binds to address ``0.0.0.0`` and port ``8080``, but can be changed via
+By default it binds to address ``0.0.0.0`` and port ``8080``, but that can be
-the ``--bind`` flag.
+changed via the ``--bind`` flag.
 
 
 Control Interface
@@ -19,8 +20,8 @@ Control Interface
 The Control HTTP interface is used by the command `kapow route` to
 administer the list of system routes.
 
-By default it binds to address ``127.0.0.1`` and port ``8081``, but can be changed
+By default it binds to address ``127.0.0.1`` and port ``8081``, but that can be
-via the ``--control-bind`` flag.
+changed via the ``--control-bind`` flag.
 
 
 Data Interface
@@ -29,5 +30,5 @@ Data Interface
 The Data HTTP interface is used by the commands ``kapow get`` and ``kapow
 set`` to exchange the data for a particular request.
 
-By default it binds to address ``127.0.0.1`` and port ``8082``, but can be changed
+By default it binds to address ``127.0.0.1`` and port ``8082``, but that can be
-via the ``--data-bind`` flag.
+changed via the ``--data-bind`` flag.

docs/source/concepts/philosophy.rst

@@ -7,17 +7,17 @@ Single Static Binary
 
 - Deployment is then as simple as it gets.
 
-- Docker-friendly.
+- ``Docker``-friendly.
 
 
 Shell Agnostic
 --------------
 
-- *Kapow!* knows nothing, and makes no assumptions, about the shell you are using.
+- *Kapow!*, like John Snow, knows nothing, and makes no assumptions about the
-  It only spawns executables.
+  shell you are using.  It only spawns executables.
 
 - You are free to implement a client to the Data API directly if you are so
-  inclined. The spec provides all the necessary details.
+  inclined.  The spec provides all the necessary details.
 
 
 Not a Silver Bullet
@@ -26,6 +26,6 @@ Not a Silver Bullet
 You should not use *Kapow!* if your project requires complex business logic.
 
 If you try to encode business logic in a shell script, you will **deeply**
-regret it.
+regret it soon enough.
 
 *Kapow!* is designed for automating simple stuff.

docs/source/concepts/request_life_cycle.rst

@@ -12,18 +12,19 @@ answered by the `User HTTP Interface`.
 
 The user makes a request to the `User HTTP Interface`.
 
-- The request is matched against the route table
+- The request is matched against the route table.
 
 - ``kapow`` provides a `HANDLER_ID` to identify this request and don't mix it
   with other requests that could be running concurrently.
 
+
 2. spawn
 --------
 
 ``kapow`` spawns the executable specified as entrypoint in the matching
 route.
 
-The default entrypoint is ``/bin/sh``; we'll explain this workflow for now.
+The default entrypoint is ``/bin/sh``; let's focus on this workflow.
 
 The spawned entrypoint is run with the following variables added to its
 environment:
@@ -32,6 +33,7 @@ environment:
 - ``KAPOW_DATAAPI_URL``: With the URL of the `Data HTTP Interface`
 - ``KAPOW_CONTROLAPI_URL``: With the URL of the `Control HTTP Interface`
 
+
 3. ``kapow set /response/body banana``
 --------------------------------------
 
@@ -43,18 +45,20 @@ available via these commands:
 - ``kapow set /response/...``
 
 These commands use the aforementioned environment variables to read data
-from the user request and to write the response.  They accept data
+from the user request and to write the response.  They accept data either as
-either as arguments or from ``stdin``.
+arguments or from ``stdin``.
+
 
 4. exit
 -------
 
-The shell dies.
+The shell dies.  Long live the shell!
+
 
 5. response
 -----------
 
-``kapow`` finalizes the original request.
+``kapow`` finalizes the original request.  Enjoy your banana now.
 
 
 .. todo::

docs/source/concepts/resource_tree.rst

@@ -4,9 +4,8 @@ The *Kapow!* Resource Tree
 This is the model that *Kapow!* uses to expose the internals of the user request
 being serviced.
 
-
+We use this tree to get access to any data that comes in the request, as well as
-We use this tree to get access to any data that comes in the request,
+to compose the response.
-as well as to compose the response.
 
 We access the resource tree easily with the ``kapow set`` and ``kapow get``
 subcommands.
@@ -47,6 +46,7 @@ Overview
       │     └──── <name>            HTTP request cookie
       └──── body                    Response body
 
+
 Resources
 ---------
 
@@ -59,13 +59,13 @@ The HTTP method of the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl -X POST http://kapow.example:8080
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/method
    POST
@@ -74,20 +74,19 @@ then, when handling the request:
 ``/request/host`` Resource
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``Host`` header as defined in the HTTP/1.1 spec of the incoming
+The ``Host`` header as defined in the HTTP/1.1 spec of the incoming request.
-request.
 
 **Sample Usage**
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl http://kapow.example:8080
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/host
    kapow.example
@@ -102,17 +101,18 @@ Contains the path substring of the URL.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl http://kapow.example:8080/foo/bar?qux=1
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/path
    /foo/bar
 
+
 ``/request/matches/<name>`` Resource
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -122,23 +122,24 @@ Contains the part of the URL captured by the pattern ``name``.
 
 For a route defined like this:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow route add /foo/{mymatch}/bar
 
 if the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl http://kapow.example:8080/foo/1234/bar
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/matches/mymatch
    1234
 
+
 ``/request/params/<name>`` Resource
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -148,13 +149,13 @@ Contains the value of the URL parameter ``name``
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl http://kapow.example:8080/foo?myparam=bar
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/params/myparam
    myparam
@@ -169,13 +170,13 @@ Contains the value of the HTTP header ``name`` of the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl -H X-My-Header=Bar http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/headers/X-My-Header
    Bar
@@ -190,17 +191,18 @@ Contains the value of the HTTP cookie ``name`` of the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
-   $ curl --cookie "MYCOOKIE=Bar" http://kapow.example:8080/
+   $ curl --cookie MYCOOKIE=Bar http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/cookies/MYCOOKIE
    Bar
 
+
 ``/request/form/<name>`` Resource
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -210,13 +212,13 @@ Contains the value of the field ``name`` of the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl -F -d myfield=foo http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/form/myfield
    foo
@@ -231,13 +233,13 @@ Contains the name of the file uploaded through the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl -F -d myfile=@filename.txt http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/files/myfile/filename
    filename.txt
@@ -252,13 +254,13 @@ Contents of the file that is being uploaded in the incoming request.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl -F -d myfile=@filename.txt http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/files/myfile/content
    ...filename.txt contents...
@@ -273,13 +275,13 @@ Raw contents of the incoming request HTTP body.
 
 If the user runs:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ curl --data-raw foobar http://kapow.example:8080/
 
 then, when handling the request:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow get /request/body
    foobar
@@ -294,7 +296,7 @@ Contains the status code given in the user response.
 
 If during the request handling:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow set /response/status 418
 
@@ -310,7 +312,7 @@ Contains the value of the header ``name`` in the user response.
 
 If during the request handling:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow set /response/headers/X-My-Header Foo
 
@@ -324,12 +326,11 @@ value ``Foo``.
 Contains the value of the cookie ``name`` that will be set to the user
 response.
 
-
 **Sample Usage**
 
 If during the request handling:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow set /response/cookies/MYCOOKIE Foo
 
@@ -346,7 +347,7 @@ Contains the value of the response HTTP body.
 
 If during the request handling:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow set /response/body foobar
 

docs/source/concepts/route_matching.rst

@@ -10,5 +10,5 @@ to.
    link routes to its section
 
 Each incoming request is matched against the routes in the route table in
-strict order, for each route in the route table, the criteria are checked.
+strict order.  For each route in the route table, the criteria are checked.
 If the request does not match, the next route in the route list is examined.

docs/source/concepts/routes.rst

@@ -6,10 +6,9 @@ the `User HTTP Interface`, and the details to handle it.
 
 *Kapow!* implements a *route table* where all routes reside.
 
-
 A route can be set like this:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kapow route add \
       -X POST \
@@ -40,7 +39,7 @@ Uniquely identifies each route. It is used for instance by ``kapow route remove
 .. note::
 
    The current implementation of *Kapow!* autogenerates a `UUID` for this field.
-   In the future the use will be able to specify a custom value.
+   In the future the user will be able to specify a custom value.
 
 
 ``method`` Route Element
@@ -48,7 +47,7 @@ Uniquely identifies each route. It is used for instance by ``kapow route remove
 
 Specifies the HTTP method for the route to match the incoming request.
 
-The route shown above will only match a ``POST`` request.
+Note that the route shown above will only match a ``POST`` request.
 
 
 ``url_pattern`` Route Element
@@ -71,7 +70,7 @@ https://github.com/gorilla/mux#examples
 This sets the executable to be spawned, along with any arguments required.
 
 In the route shown above, the entrypoint that will be run is ``/bin/bash -c``,
-which is an incomplete recipe.  It is completed by the `command` element.
+which is an incomplete recipe.  It is then completed by the `command` element.
 
 .. todo::