doc: style fixes and links

docs/source/concepts/interfaces.rst

@@ -5,29 +5,35 @@
 clear purpose.
 
 
-User Interface
+.. _http-user-interface:
---------------
 
-The `User HTTP Interface` is used to serve final user requests.
+HTTP User Interface
+-------------------
+
+The `HTTP User Interface` is used to serve final user requests.
 
 By default it binds to address ``0.0.0.0`` and port ``8080``, but that can be
 changed via the ``--bind`` flag.
 
 
-Control Interface
+.. _http-control-interface:
------------------
 
-The `Control HTTP Interface` is used by the command ``kapow route`` to
+HTTP Control Interface
+----------------------
+
+The `HTTP Control 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 that can be
 changed via the ``--control-bind`` flag.
 
 
-Data Interface
+.. _http-data-interface:
---------------
 
-The `Data HTTP Interface` is used by the commands ``kapow get`` and ``kapow
+HTTP Data Interface
+-------------------
+
+The `HTTP Data 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 that can be

docs/source/concepts/request_life_cycle.rst

@@ -2,7 +2,7 @@ Request Life Cycle
 ==================
 
 This section describes the sequence of events happening for each request
-answered by the `User HTTP Interface`.
+answered by the `HTTP User Interface`.
 
 .. image:: ../_static/request_life_cycle.png
 
@@ -10,7 +10,7 @@ answered by the `User HTTP Interface`.
 1. request
 ----------
 
-The user makes a request to the `User HTTP Interface`.
+The user makes a request to the `HTTP User Interface`.
 
 - The request is matched against the route table.
 
@@ -30,8 +30,8 @@ The spawned entrypoint is run with the following variables added to its
 environment:
 
 - :envvar:`KAPOW_HANDLER_ID`: Containing the `HANDLER_ID`
-- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the `Data HTTP Interface`
+- :envvar:`KAPOW_DATAAPI_URL`: With the URL of the `HTTP Data Interface`
-- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the `Control HTTP Interface`
+- :envvar:`KAPOW_CONTROLAPI_URL`: With the URL of the `HTTP Control Interface`
 
 
 3. ``kapow set /response/body banana``

docs/source/concepts/routes.rst

@@ -4,7 +4,7 @@ Routes
 ======
 
 A *Kapow!* route specifies the matching criteria for an incoming request on
-the `User HTTP Interface`, and the details to handle it.
+the `HTTP User Interface`, and the details to handle it.
 
 *Kapow!* implements a *route table* where all routes reside.
 

docs/source/examples/index.rst

@@ -1,18 +1,19 @@
 Using a pow File
 ++++++++++++++++
 
-A ``pow`` file is just a ``bash`` script, where you make calls to the ``kapow route``
+A :file:`pow` file is just a :command:`bash` script, where you make calls to the
-command.
+``kapow route`` command.
 
 
-**Starting** *Kapow!* **using a** ``pow`` **file**
+Starting *Kapow!* using a pow file
+----------------------------------
 
 .. code-block:: console
    :linenos:
 
    $ kapow server example.pow
 
-With the ``example.pow``:
+With the :file:`example.pow`:
 
 .. code-block:: console
    :linenos:
@@ -29,14 +30,14 @@ With the ``example.pow``:
 
 .. note::
 
-   *Kapow!* can be fully configured using just ``pow`` files
+   *Kapow!* can be fully configured using just :file:`pow` files
 
 
 Load More Than One pow File
 +++++++++++++++++++++++++++
 
-You can load more than one ``pow`` file at time.  This can help you keep your
+You can load more than one :file:`pow` file at time.  This can help you keep
-``pow`` files tidy.
+your :file:`pow` files tidy.
 
 .. code-block:: console
    :linenos:
@@ -54,7 +55,8 @@ Add a New Route
     Be aware that if you register more than one route with exactly the
     same path, only the first route added will be used.
 
-**GET route**
+GET route
+---------
 
 Defining a route:
 
@@ -72,9 +74,10 @@ Calling route:
    $ curl http://localhost:8080/my/route
    hello world
 
-**POST route**
+POST route
+----------
 
-Defining route:
+Defining a route:
 
 .. code-block:: console
    :linenos:
@@ -82,7 +85,7 @@ Defining route:
    $ kapow route add -X POST /echo -c 'kapow get /request/body | kapow set /response/body'
 
 
-Calling route:
+Calling a route:
 
 .. code-block:: console
    :linenos:
@@ -91,9 +94,10 @@ Calling route:
    hello world
 
 
-**Adding URL params**
+Adding URL params
+-----------------
 
-Defining route:
+Defining a route:
 
 .. code-block:: console
    :linenos:
@@ -101,7 +105,7 @@ Defining route:
    $ kapow route add '/echo/{message}' -c 'kapow get /request/matches/message | kapow set /response/body'
 
 
-Calling route:
+Calling a route:
 
 .. code-block:: console
    :linenos:
@@ -115,7 +119,7 @@ Listing Routes
 
 You can list the active routes in the *Kapow!* server.
 
-.. _examples_listing_routes:
+.. _listing-routes-example:
 
 .. code-block:: console
    :linenos:
@@ -142,16 +146,17 @@ Or, if you want human-readable output, you can use :program:`jq`:
 
 .. note::
 
-   *Kapow!* has a `Control HTTP Interface`, bound by default to
+   *Kapow!* has a :ref:`http-control-interface`, bound by default to
-   ``localhost:8081``
+   ``localhost:8081``.
 
 
 Deleting Routes
 +++++++++++++++
 
 You need the ID of a route to delete it.
-Using the :ref:`listing routes example <examples_listing_routes>`, you can
+Running the command used in the :ref:`listing routes example
-obtain the ID of the route, and then delete it by typing:
+<listing-routes-example>`, you can obtain the ID of the route, and then delete
+it by typing:
 
 .. code-block:: console
    :linenos:

docs/source/the_project/security.rst

@@ -55,7 +55,7 @@ makes this request:
 
 Let's see what happens:
 
-The command that will eventually be executed by ``bash`` is:
+The command that will eventually be executed by :command:`bash` is:
 
 .. code-block:: bash
 

docs/source/tutorial/tutorial01.rst

@@ -1,5 +1,5 @@
-Backup that Database!
+Let's Backup that Database!
-=====================
+===========================
 
 **Junior**
 
@@ -11,8 +11,8 @@ Backup that Database!
   project team ask us for a backup every time a project is finished.
 
   I've already prepared a script to do the task.  Before executing it in
-  production, :download:`download it <./materials/backup_db.sh>` and test it in
+  production, why don't you :download:`download it <./materials/backup_db.sh>`
-  your own machine.
+  and test it in your laptop?
 
   .. code-block:: console
 
@@ -23,7 +23,7 @@ Backup that Database!
 
   (after a few minutes)
 
-  OK, done!  When I executed it the output says:
+  OK, done!  I just run it and I got this output:
 
   .. code-block:: console
 
@@ -35,9 +35,9 @@ Backup that Database!
 
   That's right.  That script performed the backup and stored it into the
   **Backup Server** and appended some information into the backup log file at
-  ``/tmp/backup_db.log``.
+  :file:`/tmp/backup_db.log`.
 
-  Now you can ``ssh`` into the **Corporate Server** and make the real
+  Now you can :program:`ssh` into the **Corporate Server** and make the real
   backup.
 
 
@@ -57,22 +57,21 @@ Backup that Database!
 
 **Senior**
 
-  I am the only one allowed to ``ssh`` into the **Corporate Server**, for
+  I am the only one allowed to :program:`ssh` into the **Corporate Server**, for
   obvious reasons.
 
 **Junior**
 
-  Why do you need to ``ssh`` in the first place?  Couldn't it be done without
+  Why do you need to :program:`ssh` in the first place?  Couldn't it be done
-  ``ssh``?
+  without :program:`ssh`?
 
 **Senior**
 
   Actually, it could be done with a promising new tool I've just found...
   *Kapow!*
 
-  Is a tool that allows you to publish scripts as ``HTTP`` services.  If we
+  Is a tool that allows you to publish scripts as `HTTP` services.  If we use it
-  use it here we can give them the ability to do the backup whenever
+  here we can give them the ability to do the backup whenever they want.
-  they want.
 
 **Junior**
 
@@ -92,10 +91,10 @@ Backup that Database!
 
 **Senior**
 
-  Don't worry, it is pretty easy.  Basically we will provide an ``HTTP``
+  Don't worry, it is pretty easy.  Basically we will provide an `HTTP` endpoint
-  endpoint managed by *Kapow!* at the **Corporate Server**; when the project
+  managed by *Kapow!* at the **Corporate Server**; when the project team wants
-  team wants to perform a backup they only need to call the endpoint and
+  to perform a backup they only need to call the endpoint and *Kapow!* will call
-  *Kapow!* will call the backup script.
+  the backup script.
 
 **Junior**
 
@@ -116,11 +115,11 @@ Backup that Database!
 
 **Junior**
 
-  Done! But it doesn't do anything.
+  Done!  But it doesn't seem to do anything...
 
 **Senior**
 
-  Now you have the port ``8080`` open but don't have any endpoints defined.
+  Now you have the port ``8080`` open, but no endpoints have been defined yet.
   To define our endpoint you have to run this in another terminal:
 
   .. code-block:: console
@@ -140,7 +139,8 @@ Backup that Database!
 
   Not at all.  The creators of *Kapow!* have thought of everything.  You can put
   all your route definitions in a special script file and pass it to the server
-  on startup.  They call those files `pow` files and they have ``.pow`` extension.
+  on startup.  They call those files :file:`pow` files and they have
+  :file:`.pow` extension.
 
   It should look something like:
 
@@ -180,11 +180,11 @@ Backup that Database!
 
 **Junior**
 
-  Yay!  I can see the log file at ``/tmp/backup_db.log``
+  Yay!  I can see the log file at :file:`/tmp/backup_db.log`
 
 **Senior**
 
-  That's great.  I am going to install all this in the *Corporate Server* and
+  That's great.  I am going to install all this in the **Corporate Server** and
   forget about the old procedure.
 
   That enough for your first day!  Go home now and get some rest.

docs/source/tutorial/tutorial02.rst

@@ -3,16 +3,16 @@ What have we done?
 
 **Senior**
 
-  Ey, I come from seeing our project team mates.  They're delighted with their
+  Hey, I come from seeing our project team mates.  They're delighted with their
   new toy, but they miss something.
 
   I forgot to tell you that after the backup is run they need to review the log
-  file to check that all went OK.
+  file to check that everything went OK.
 
 **Junior**
 
   Makes sense.  Do you think that *Kapow!* can help with this?  I have the
-  feeling that this is the right way to do it...
+  feeling that this is the right way to go about it...
 
 **Senior**
 
@@ -27,7 +27,7 @@ What have we done?
 
 **Senior**
 
-  Yeah, the team is used to :command:`cat`` the log file contents to see what
+  Yeah, the team is used to :command:`cat` the log file contents to see what
   happened in the last execution:
 
   .. code-block:: console
@@ -38,7 +38,7 @@ What have we done?
 
 **Junior**
 
-  Let me try add this to our ``pow`` file:
+  Let me try add this to our :file:`pow` file:
 
   .. code-block:: console
 
@@ -47,7 +47,7 @@ What have we done?
 **Senior**
 
   Looks good to me, clean and simple, and it is a very good idea to use ``GET``
-  here as it wont change anything in the server.  Restart *Kapow!* and try it.
+  here as it wont change anything in the server.  Let's restart *Kapow!* and try it.
 
 **Junior**
 
@@ -56,4 +56,4 @@ What have we done?
 
 **Senior**
 
-  Agree.  We are done for the day with this...
+  Agreed.  And with this, I think we are done for the day...

docs/source/tutorial/tutorial03.rst

@@ -53,7 +53,7 @@ We need to filter
        | kapow set /response/body'
 
   It looks a bit weird, but we'll have time to revise the style later.  Please
-  make some tests on your laptop before we publish it on the *Corporate Server*.
+  make some tests on your laptop before we publish it on the **Corporate Server**.
   Remember to send them an example URL with the parameters they can use to
   filter and limit the amount of lines they get.
 

docs/source/tutorial/tutorial04.rst

@@ -184,11 +184,11 @@ I Need my Report!
 
 **Senior**
 
-  There is a better way.  You can make use of another neat ``bash`` feature:
+  There is a better way.  You can make use of another neat :command:`bash`
-  **group commands**.
+  feature:  `command grouping`_.
 
-  Group commands allows you to execute several commands treating the
+  Command grouping allows you to execute several commands treating the group as
-  group as one single command.
+  one single command.
 
   You can use this way:
 
@@ -226,3 +226,5 @@ I Need my Report!
   You know me.  Whatever it takes to avoid writing reports ;-)
 
   (both chuckle).
+
+.. _command grouping: https://www.gnu.org/software/bash/manual/html_node/Command-Grouping.html

docs/source/tutorial/tutorial05.rst

@@ -64,7 +64,7 @@ Sharing the Stats
 
 **Senior**
 
-  See it for yourself.
+  See for yourself.
 
   .. code-block:: console
 
@@ -170,7 +170,7 @@ Sharing the Stats
 
 **Senior**
 
-  You are right, but you are not using ``HTTP`` correctly.  You have to set the
+  You are right, but you are not using `HTTP` correctly.  You have to set the
   ``Content-Type`` header to let your client know the format of the data you are
   outputting.
 
@@ -227,5 +227,5 @@ Sharing the Stats
 
 **Senior**
 
-  That's perfect!  Now, let's upload this to the *Corporate Server* and tell the
+  That's perfect!  Now, let's upload this to the **Corporate Server** and tell the
   frontend developer about it.