Ticket #6180: proposed.rewords.patch

defer-intro.xhtml

@@ -15 +15 @@
   This document introduces <code base="twisted.internet.defer"
   class="API">Deferred</code>s, Twisted's preferred mechanism for controlling
   the flow of asynchronous code.  Don't worry if you don't know what that means
-  yet, as the rest of this document sets out to explain exactly that.
+  yet! That's why you are here!
 </p>
 
 <p>
@@ -261 +261 @@
 </p>
 
 <p>
-  So, we've replaced the <q>order of lines is order of execution</q> with a
-  deliberate, in-Python encoding of the order of execution,
-  where <code class="python">d</code> represents the particular flow and
-  <code class="python">d.addCallback</code> replaces <q>new line</q>.
+  So, we've replaced the <q>order of lines is order of execution</q> model with a
+  deliberate, in-Python encoding of the order of execution.
+  The control-flow is represented by <code class="python">d</code>,
+  and <code class="python">d.addCallback</code> declares your <q>next actions</q>.
 </p>
 
-<h2>A catalog of failures</h2>
-
 <p>
-  Of course, programs generally consist of more than two lines, and exceptions
-  add a delicate and pleasing spice to the whole experience.
+  So far, so good.
 </p>
 
+<h2>Getting it right: The failure cases</h2>
+
 <p>
-  In what follows, we are going to take each way of expressing order of
-  operations in Python using sequences of lines
-  and <code class="python">try</code>/<code class="python">except</code> and
-  translate them into an equivalent built with <code class="API"
-  base="twisted.internet.defer">Deferred</code>.
+  In what follows, we are going to take each different way of expressing
+  order of operations in normal Python (with code lines and
+  <code class="python">try</code>/<code class="python">except</code>) and
+  translate them into an equivalent code built with <code class="API"
+  base="twisted.internet.defer">Deferred</code> objects.
 </p>
 
 <p>
-  This is going to be a bit painstaking, but if you want to really understand
-  how to use <code class="API" base="twisted.internet.defer">Deferred</code>s
-  and how to understand and maintain code that uses <code class="API"
-  base="twisted.internet.defer">Deferred</code>s, it is worth understanding
-  each of these examples.
+  This is going to be a bit painstaking, but if you really want to understand
+  how to use <code class="API" base="twisted.internet.defer">Deferred</code>s,
+  and maintain code that uses them, then it's worth understanding each example
+  below.
 </p>
 
 <h3>One thing, then another, then another</h3>
@@ -469 +467 @@
 <p>
   The order of <code class="python">addErrback</code>
   and <code class="python">addCallback</code> matters.  In the next section, we
-  can see what would happen when we them around.
+  can see what will happen when we swap them around.
 </p>
 
 <h3>Handle an error for the entire operation</h3>