docs: concurrency, developing scripts

3 files changed, 20 insertions, 32 deletions

diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst
index 744f5eb4..5966eb1d 100644
--- a/docs/scripting/overview.rst
+++ b/docs/scripting/overview.rst
@@ -105,38 +105,37 @@ flow loaded from disk will trigger `requestheaders
 traffic using scripts. For example, we can invoke the replacer script from
 above on saved traffic as follows:
 
->>> mitmdump -dd -s "./arguments.py html faketml"
-
-
-
+>>> mitmdump -dd -s "./arguments.py html fakehtml" -r saved -w changed
 
+This command starts the ``arguments`` script, reads all the flows from
+``saved`` transforming them in the process, then writes them all to
+``changed``.
 
-:py:class:`~mitmproxy.models.Flow`
-objects that are already complete.  This happens when you start a script, and
-then load a saved set of flows from a file (see the "scripted data
-transformation" example :ref:`here <mitmdump>`). It also happens when you run a
-one-shot script on a single flow through the ``|`` (pipe) shortcut in
-mitmproxy.
-
-In this case, there are no client connections, and the events are run in the following order:
-**start**, **request**, **responseheaders**, **response**, **error**, **done**.
-If the flow doesn't have a **response** or **error** associated with it, the matching events will
-be skipped.
+The mitmproxy console tool provides interactive ways to run transforming
+scripts on flows - for instance, you can run a one-shot script on a single flow
+through the ``|`` (pipe) shortcut.
 
 
 Concurrency
 -----------
 
-We have a single flow primitive, so when a script is blocking, other requests
-are not processed. While that's usually a very desirable behaviour, blocking
-scripts can be run threaded by using the :py:obj:`mitmproxy.script.concurrent`
-decorator.
+The mitmproxy script mechanism is single threaded, and the proxy blocks while
+script handlers execute. This hugely simplifies the most common case, where
+handlers are light-weight and the blocking doesn't have a performance impact.
+It's possible to implement a concurrent mechanism on top of the blocking
+framework, and mitmproxy includes a handy example of this that is fit for most
+purposes. You can use it as follows:
 
 .. literalinclude:: ../../examples/nonblocking.py
    :caption: :src:`examples/nonblocking.py`
    :language: python
 
 
-
 Developing scripts
 ------------------
+
+Mitmprxoy monitors scripts for modifications, and reloads them on change. When
+this happens, the script is shut down (the `done <events.html#done>`_  event is
+called), and the new instance is started up as if the script had just been
+loaded (the `start <events.html#start>`_ and `configure
+<events.html#configure>`_ events are called).
diff --git a/mitmproxy/builtins/script.py b/mitmproxy/builtins/script.py
index 5c375d27..9bf25703 100644
--- a/mitmproxy/builtins/script.py
+++ b/mitmproxy/builtins/script.py
@@ -267,7 +267,7 @@ class ScriptLoader():
 
             ochain = ctx.master.addons.chain
             pos = ochain.index(self)
-            ctx.master.addons.chain = ochain[:pos+1] + ordered + ochain[pos+1:]
+            ctx.master.addons.chain = ochain[:pos + 1] + ordered + ochain[pos + 1:]
 
             for s in newscripts:
                 ctx.master.addons.startup(s)
diff --git a/release/README.mkd b/release/README.mkd
index 7754125d..8d63b8f3 100644
--- a/release/README.mkd
+++ b/release/README.mkd
@@ -1,15 +1,4 @@
 
-General build and release utilities for the mitmproxy, netlib and pathod
-projects. These tools assume a directory structure with all repositories at the
-same level, for example:
-
-    /src
-        /mitmproxy
-        /netlib
-        /pathod
-        /release
-
-
 # Release policies
 
   - By default, every release is a new minor (`0.x`) release and it will be