Ticket #4568: core-howto2.xhtml.patch

doc/core/howto/components.xhtml

@@ -101 +101 @@
 inheritance to break code into small reusable chunks. Let us continue with the
 Multiple Inheritance example, though, because it is often used in practice.</p>
 
-<p>What if both the Color and the Area base class defined the same method,
-perhaps <code>calculate</code>? Where would the implementation come from? The
-implementation that is located for <code>Square().calculate()</code> depends on
-the method resolution order, or MRO, and can change when programmers change
-seemingly unrelated things by refactoring classes in other parts of the system,
-causing obscure bugs. Our first thought might be to change the calculate method
-name to avoid name clashes, to perhaps <code>calculateArea</code> and 
-<code>calculateColor</code>.  While explicit, this change could potentially
-require a large number of changes throughout a system, and is error-prone,
-especially when attempting to integrate two systems which you didn't write.</p>
+<p>What if both the Color and the Area base class defined the same
+method, perhaps <code>calculate</code>? Where would the implementation
+come from? The implementation that is located
+for <code>Square().calculate()</code> depends on the method resolution
+order, or MRO, and can change when programmers change seemingly
+unrelated things by refactoring classes in other parts of the system,
+causing obscure bugs. Our first thought might be to change the
+calculate method name to avoid name clashes, to
+perhaps <code>calculateArea</code> and <code>calculateColor</code>.
+While explicit, this change could potentially require a large number
+of changes throughout a system, and is error-prone, especially when
+attempting to integrate two systems which you didn't write.</p>
 
 <p>Let's imagine another example. We have an electric appliance, say a hair
 dryer. The hair dryer is American voltage. We have two electric sockets, one of
@@ -152 +154 @@
 now you have no hair dryer any more.
 </pre>
 
-<p>We are going to attempt to solve this problem by writing an Adapter for the 
-<code>UKSocket</code> which converts the voltage for use with an American
+<p>We are going to attempt to solve this problem by writing an Adapter for 
+the <code>UKSocket</code> which converts the voltage for use with an American
 hair dryer. An Adapter is a class which is constructed with one and only one
 argument, the <q>adaptee</q> or <q>original</q> object. In this example, we
 will show all code involved for clarity:</p>
@@ -216 +218 @@
 distinguishes an Interface definition from a Class.</p>
 
 <p>Now that we have a defined Interface, we can talk about objects using terms
-like this: <q>The <code>AmericanSocket</code> class implements the
-<code>IAmericanSocket</code> interface</q> and <q>Please give me an object which
+like this: <q>The <code>AmericanSocket</code> class implements the <code>IAmericanSocket</code> interface</q> and <q>Please give me an object which
 adapts <code>UKSocket</code> to the <code>IAmericanSocket</code>
 interface</q>. We can make <em>declarations</em> about what interfaces a certain
 class implements, and we can request adapters which implement a certain
@@ -236 +237 @@
         return 120
 </pre>
 
-<p>So, to declare that a class implements an interface, we simply call 
-<code>zope.interface.implements</code> at the class level.</p>
+<p>So, to declare that a class implements an interface, we simply
+call <code>zope.interface.implements</code> at the class level.</p>
 
-<p>Now, let's say we want to rewrite the <code>AdaptToAmericanSocket</code>
-class as a real adapter. In this case we also specify it as implementing 
-<code>IAmericanSocket</code>:</p>
+<p>Now, let's say we want to rewrite
+the <code>AdaptToAmericanSocket</code> class as a real adapter. In
+this case we also specify it as
+implementing <code>IAmericanSocket</code>:</p>
 
 <pre class="python">
 from zope.interface import implements
@@ -325 +327 @@
 
 <p>As you can see, the <code>AmericanSocket</code> instance claims to
 implement <code>IAmericanSocket</code>, but the <code>UKSocket</code>
-does not. If we wanted to use the <code>HairDryer</code> with the 
-<code>AmericanSocket</code>, we could know that it would be safe to do so by
+does not. If we wanted to use the <code>HairDryer</code> with the <code>AmericanSocket</code>, we could know that it would be safe to do so by
 checking whether it implements <code>IAmericanSocket</code>. However, if we
 decide we want to use <code>HairDryer</code> with a <code>UKSocket</code>
 instance, we must <em>adapt</em> it to <code>IAmericanSocket</code> before
@@ -341 +342 @@
 looks in the adapter registry for an adapter which implements the interface for
 the given instance's class. If it finds one, it constructs an instance of the
 Adapter class, passing the constructor the original instance, and returns it.
-Now the <code>HairDryer</code> can safely be used with the adapted 
-<code>UKSocket</code>. But what happens if we attempt to adapt an object
+Now the <code>HairDryer</code> can safely be used with the adapted  <code>UKSocket</code>. But what happens if we attempt to adapt an object
 which already implements <code>IAmericanSocket</code>? We simply get back the
 original instance:</p>
 
@@ -432 +432 @@
 True
 </pre>
 
-<p>If you want <code>MyThing</code> to inherit from <code>pb.Root</code> but 
-<em>not</em> implement <code>IPBRoot</code> like <code>pb.Root</code> does,
+<p>If you want <code>MyThing</code> to inherit from <code>pb.Root</code> but <em>not</em> implement <code>IPBRoot</code> like <code>pb.Root</code> does,
 use <code>implementOnly</code>:</p>
 
 <pre class="python">

doc/core/howto/defer.xhtml

@@ -44 +44 @@
 available (this series of functions is known as a series of 
 <strong>callbacks</strong>, or a <strong>callback chain</strong>), together
 with a series of functions to be called if there is an error in the
-asychronous request (known as a series of <strong>errbacks</strong> or an 
-<strong>errback chain</strong>). The asychronous library code calls the first
+asychronous request (known as a series of <strong>errbacks</strong> or an  <strong>errback chain</strong>). The asychronous library code calls the first
 callback when the result is available, or the first errback when an error
 occurs, and the <code>Deferred</code> object then hands the results of each
 callback or errback function to the next function in the chain.</p> 
@@ -305 +304 @@
 <p>What this means in a practical sense is in Case 1, the callback in line
 A will handle a success condition from <code>getDeferredFromSomewhere</code>,
 and the errback in line B will handle any errors that occur <em>from either the
-upstream source, or that occur in A</em>.  In Case 2, the errback in line C 
-<em>will only handle an error condition raised by</em>
-<code>getDeferredFromSomewhere</code>, it will not do any handling of errors
+upstream source, or that occur in A</em>.  In Case 2, the errback in line C  <em>will 
+only handle an error condition raised by</em> <code>getDeferredFromSomewhere</code>, 
+it will not do any handling of errors
 raised in <code>callback1</code>.</p>
 
 
@@ -391 +390 @@
     return d
 </pre>
 
-<p> Our original implementation of <code>authenticateUser</code> expected 
-<code>isValidUser</code> to be synchronous, but now we need to change it to handle both
+<p> Our original implementation of <code>authenticateUser</code> expected  <code>isValidUser</code> to be synchronous, but now we need to change it to handle both
 synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we
 use <code class="API" base="twisted.internet.defer">maybeDeferred</code> to
 call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,
@@ -414 +412 @@
 </pre>
 
 <p>
-Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or 
-<code>asynchronousIsValidUser</code>.
+Now <code>isValidUser</code> could be either <code>synchronousIsValidUser</code> or  <code>asynchronousIsValidUser</code>.
 </p>
 
 <p>It is also possible to modify <code>synchronousIsValidUser</code> to return
@@ -437 +434 @@
 dl = defer.DeferredList([deferred1, deferred2, deferred3])
 </pre>
 
-<p>You can now treat the DeferredList like an ordinary Deferred; you can call 
-<code>addCallbacks</code> and so on.  The DeferredList will call its callback
+<p>You can now treat the DeferredList like an ordinary Deferred; you can call  <code>addCallbacks</code> and so on.  The DeferredList will call its callback
 when all the deferreds have completed.  The callback will be called with a list
 of the results of the Deferreds it contains, like so:</p>
 
@@ -552 +548 @@
 class="footnote">Unless of course a later callback starts a fresh error &mdash;
 but as we've already noted, adding callbacks to a Deferred after its used in a
 DeferredList is confusing and usually avoided.</span>.  Passing a true value
-for the <code>consumeErrors</code> parameter will not change the behavior of 
-<code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
+for the <code>consumeErrors</code> parameter will not change the behavior of <code>fireOnOneCallback</code> or <code>fireOnOneErrback</code>.</p>
 
 <a name="class"></a>
 
@@ -564 +559 @@
 substitute for the docstrings in the Deferred class, but can provide guidelines
 for its use.</p>
 
-<p>There is a parallel overview of functions used by the Deferred's 
-<em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
+<p>There is a parallel overview of functions used by the Deferred's  <em>creator</em> in <a href="gendefer.xhtml#class">Generating Deferreds</a>.</p>
 
 <h3>Basic Callback Functions</h3>
 

doc/core/howto/udp.xhtml

@@ -89 +89 @@
 class Helloer(DatagramProtocol):
 
     def startProtocol(self):
-        host = "192.168.1.1"
-        port = 1234
+        host = "192.168.1.1"
+        port = 1234
 
         self.transport.connect(host, port)
         print "now we can only send to host %s port %d" % (host, port)

doc/core/howto/pb-intro.xhtml

@@ -208 +208 @@
 <p>There are 2 basic flavors that allow for copying objects remotely.  Again,
 you can use these by subclassing them.  In order to specify what state you want
 to have copied when these are serialized, you can either use the Python default 
-<code class="python">__getstate__</code> or specialized method calls for that
+ <code class="python">__getstate__</code> or specialized method calls for that
 flavor.</p>
 
 <p>

doc/core/howto/internet-overview.xhtml

@@ -19 +19 @@
 <p>Twisted Internet contains the various interfaces to the reactor
 API, whose usage is documented in the low-level chapter. Those APIs
 are <code class="API" base="twisted.internet.interfaces">IReactorCore</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorTCP</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorSSL</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorUNIX</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorUDP</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorTime</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorProcess</code>, 
-<code class="API" base="twisted.internet.interfaces">IReactorMulticast</code> 
+ <code class="API" base="twisted.internet.interfaces">IReactorTCP</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorSSL</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorUNIX</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorUDP</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorTime</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorProcess</code>, 
+ <code class="API" base="twisted.internet.interfaces">IReactorMulticast</code> 
 and <code class="API" base="twisted.internet.interfaces">IReactorThreads</code>.
 The reactor APIs allow non-persistent calls to be made.</p>
 

doc/core/howto/deferredindepth.xhtml

@@ -12 +12 @@
 <p>Deferreds are quite possibly the single most confusing topic that a
 newcomer to Twisted has to deal with. I am going to forgo the normal talk
 about what deferreds are, what they aren't, and why they're used in Twisted.
-Instead, I'm going show you the logic behind what they 
-<strong>do</strong>.</p>
+Instead, I'm going show you the logic behind what they <strong>do</strong>.</p>
 
 
 <p>A deferred allows you to encapsulate the logic that you'd normally use to
@@ -255 +254 @@
 </pre>
 
 <p>Two things to note here. First, &quot;- A -&quot; was skipped, like we wanted it to,
-and the second thing is that after &quot;- A -&quot;, noDecision is called, because 
-<strong>it is the next errback that exists in the chain</strong>. It returns a
+and the second thing is that after &quot;- A -&quot;, noDecision is called, because  <strong>it is the next errback that exists in the chain</strong>. It returns a
 non-failure, so processing continues with the next callback at &quot;- B -&quot;, and
 the errback at the end of the chain is never called </p>
 

doc/core/howto/pb-copyable.xhtml

@@ -75 +75 @@
 protocol that involved sending a file-like object with a <code>read()</code>
 method that was supposed to used later to retrieve a document. Then imagine
 what if that object were created with 
-<code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of 
-<code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
+ <code>os.fdopen("~/.gnupg/secring.gpg")</code>. Or an instance of 
+ <code>telnetlib.Telnet("localhost", "chargen")</code>. </p>
 
 <p>Classes you've written for your own program are likely to have far more
 power. They may run code during <code>__init__</code>, or even have special
 meaning simply because of their existence. A program might have 
-<code>User</code> objects to represent user accounts, and have a rule that
+ <code>User</code> objects to represent user accounts, and have a rule that
 says all <code>User</code> objects in the system are referenced when
 authorizing a login session. (In this system, <code>User.__init__</code>
 would probably add the object to a global list of known users). The simple
@@ -127 +127 @@
 that a serialized representation A (of some remote object) can be
 unserialized into a local object of type B. It is these objects <q>B</q>
 that are the <q>Unjellyable</q> second argument of the 
-<code>setUnjellyableForClass</code> function.
+ <code>setUnjellyableForClass</code> function.
 In particular, <q>unjellyable</q> does <em>not</em> mean <q>cannot be
 jellied</q>. <code class="API"
 base="twisted.spread.jelly">Unpersistable</code> means <q>not
@@ -143 +143 @@
 the remote end sends an object, the class name that they transmit is looked
 up in the table controlled by this function. If a matching class is found,
 it is used to create the local object. If not, you get the 
-<code>InsecureJelly</code> exception.</p>
+ <code>InsecureJelly</code> exception.</p>
 
 <p>In general you expect both ends to share the same codebase: either you
 control the program that is running on both ends of the wire, or both
@@ -152 +152 @@
 the MyFooziWhatZit class unless you also had a definition for that class. So
 it is reasonable for the Jelly layer to reject all incoming classes except
 the ones that you have explicitly marked with 
-<code>setUnjellyableForClass</code>. But keep in mind that the sender's idea
+ <code>setUnjellyableForClass</code>. But keep in mind that the sender's idea
 of a <code>User</code> object might differ from the recipient's, either
 through namespace collisions between unrelated packages, version skew
 between nodes that haven't been updated at the same rate, or a malicious
@@ -175 +175 @@
 base="twisted.spread.pb">Serializable</code> classes. In this section,
 we focus on <code class="API" base="twisted.spread.pb">Copyable</code>.
 The copyable subclass of <code>LilyPond</code> is called 
-<code>CopyPond</code>. We create an instance of it and send it through 
-<code>callRemote</code> as an argument to the receiver's 
-<code>remote_takePond</code> method. The Jelly layer will serialize
+ <code>CopyPond</code>. We create an instance of it and send it through 
+ <code>callRemote</code> as an argument to the receiver's 
+ <code>remote_takePond</code> method. The Jelly layer will serialize
 (<q>jelly</q>) that object as an instance with a class name of
 <q>copy_sender.CopyPond</q> and some chunk of data that represents the
 object's state. <code>pond.__class__.__module__</code> and 
-<code>pond.__class__.__name__</code> are used to derive the class name
+ <code>pond.__class__.__name__</code> are used to derive the class name
 string. The object's <code class="API"
 base="twisted.spread.flavors.Copyable">getStateToCopy</code> method is
 used to get the state: this is provided by <code class="API"
 base="twisted.spread">pb.Copyable</code>, and the default just retrieves 
-<code>self.__dict__</code>. This works just like the optional 
-<code>__getstate__</code> method used by <code>pickle</code>. The pair of
+ <code>self.__dict__</code>. This works just like the optional 
+ <code>__getstate__</code> method used by <code>pickle</code>. The pair of
 name and state are sent over the wire to the receiver.</p>
 
 <p>The receiving end defines a local class named <code>ReceiverPond</code>
@@ -200 +200 @@
 base="twisted.spread">pb.RemoteCopy</code>, which is a requirement for all
 classes that act in this local-representative role (those which are given to
 the second argument of <code>setUnjellyableForClass</code>). 
-<code>RemoteCopy</code> provides the methods that tell the Jelly layer how
+ <code>RemoteCopy</code> provides the methods that tell the Jelly layer how
 to create the local object from the incoming serialized state.</p>
 
 <p>Then <code>setUnjellyableForClass</code> is used to register the two
@@ -212 +212 @@
 <p>When the receiver unserializes (<q>unjellies</q>) the object, it will
 create an instance of the local <code>ReceiverPond</code> class, and hand
 the transmitted state (usually in the form of a dictionary) to that object's 
-<code class="API"
+ <code class="API"
 base="twisted.spread.flavors.RemoteCopy">setCopyableState</code> method.
 This acts just like the <code>__setstate__</code> method that 
-<code>pickle</code> uses when unserializing an object. 
-<code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from 
-<code>__getstate__</code>/<code>__setstate__</code> to allow objects to be
+ <code>pickle</code> uses when unserializing an object. 
+ <code>getStateToCopy</code>/<code>setCopyableState</code> are distinct from 
+ <code>__getstate__</code>/<code>__setstate__</code> to allow objects to be
 persisted (across time) differently than they are transmitted (across
 [memory]space).</p>
 
@@ -246 +246 @@
 <h3>Controlling the Copied State</h3>
 
 <p>By overriding <code>getStateToCopy</code> and 
-<code>setCopyableState</code>, you can control how the object is transmitted
+ <code>setCopyableState</code>, you can control how the object is transmitted
 over the wire. For example, you might want perform some data-reduction:
 pre-compute some results instead of sending all the raw data over the wire.
 Or you could replace references to a local object on the sender's side with
@@ -261 +261 @@
 system. Combined with the fact that <code>Copyable</code> objects return
 unchanged from a round trip, this could be used to build a
 challenge-response system (in fact PB does this with 
-<code>pb.Referenceable</code> objects to implement authorization as
+ <code>pb.Referenceable</code> objects to implement authorization as
 described <a href="pb-cred.xhtml">here</a>).</p>
 
 <p>Whatever <code>getStateToCopy</code> returns from the sending object will
@@ -422 +422 @@
 useful to subclass or modify, so simply treat it as a little demon that sits
 in your <code>pb.Cacheable</code> class and helps you distribute change
 notifications. The only useful thing to do with it is to run its
-<code>callRemote</code> method, which acts just like a normal
-<code>pb.Referenceable</code>'s method of the same name.</span> that points at that receiver-side cache. Every time the state of the object
+ <code>callRemote</code> method, which acts just like a normal
+ <code>pb.Referenceable</code>'s method of the same name.</span> that points at that receiver-side cache. Every time the state of the object
 is changed, you give a message to the observer, informing them of the
 change. The other method, <code>stoppedObserving</code>, is called when the
 remote cache goes away, so that you can stop sending updates.</p>
 
 <p>On the receiver end, you make your cache class inherit from <code
 class="API" base="twisted.spread">pb.RemoteCache</code>, and implement the 
-<code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>
+ <code>setCopyableState</code> as you would for a <code>pb.RemoteCopy</code>
 object. In addition, you must implement methods to receive the updates sent
 to the observer by the <code>pb.Cacheable</code>: these methods should have
 names that start with <code>observe_</code>, and match the 
-<code>callRemote</code> invocations from the sender side just as the usual 
-<code>remote_*</code> and <code>perspective_*</code> methods match normal 
-<code>callRemote</code> calls. </p>
+ <code>callRemote</code> invocations from the sender side just as the usual 
+ <code>remote_*</code> and <code>perspective_*</code> methods match normal 
+ <code>callRemote</code> calls. </p>
 
 <p>The first time a reference to the <code>pb.Cacheable</code> object is
 sent to any particular recipient, a sender-side Observer will be created for
@@ -447 +447 @@
 described above (in fact it inherits from that class). </p>
 
 <p>After that, your <q>setter</q> functions on the sender side should call 
-<code>callRemote</code> on the Observer, which causes <code>observe_*</code>
+ <code>callRemote</code> on the Observer, which causes <code>observe_*</code>
 methods to run on the receiver, which are then supposed to update the
 receiver-local (cached) state.</p>
 
@@ -463 +463 @@
 
 <p>With the <code>pb.Cacheable</code> and <code>pb.RemoteCache</code>
 classes in place, bound together by a call to 
-<code>pb.setUnjellyableForClass</code>, all that remains is to pass a
+ <code>pb.setUnjellyableForClass</code>, all that remains is to pass a
 reference to your <code>pb.Cacheable</code> over the wire to the remote end.
 The corresponding <code>pb.RemoteCache</code> object will automatically be
 created, and the matching methods will be used to keep the receiver-side

doc/core/howto/glossary.xhtml

@@ -307 +307 @@
 
 <dt><a name="SUX">SUX</a></dt>
 <dd><em>S</em>mall <em>U</em>ncomplicated <em>X</em>ML, Twisted's simple XML
-parser written in pure Python.  See 
-<code class="API">twisted.web.sux</code>.</dd>
+parser written in pure Python.  See <code class="API">twisted.web.sux</code>.</dd>
 
 <dt><a name="TAC">TAC</a></dt>
 <dd>A <em>T</em>wisted <em>A</em>pplication <em>C</em>onfiguration is a Python

doc/core/howto/pb-cred.xhtml

@@ -34 +34 @@
 
 <p>Imagine how you would write a chat server using PB. The first step might
 be a <code>ChatServer</code> object which had a bunch of 
-<code>pb.RemoteReference</code>s that point at user clients. Pretend that
+ <code>pb.RemoteReference</code>s that point at user clients. Pretend that
 those clients offered a <code>remote_print</code> method which lets the
 server print a message on the user's console. In that case, the server might
 look something like this:</p>
@@ -60 +60 @@
 </pre>
 
 <p>For now, assume that all clients have somehow acquired a 
-<code>pb.RemoteReference</code> to this <code>ChatServer</code> object,
+ <code>pb.RemoteReference</code> to this <code>ChatServer</code> object,
 perhaps using <code>pb.Root</code> and <code>getRootObject</code> as
 described in the <a href="pb-usage.xhtml">previous chapter</a>. In this
 scheme, when a user sends a message to the group, their client runs
@@ -99 +99 @@
 place to keep state is in an object, so this suggests we need a per-user
 object. Rather than choosing an obvious name<span class="footnote">The
 obvious name is clearly 
-<code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because
+ <code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because
 Python makes everything else so easy to read, it only seems fair to make
 your audience work for <em>something</em>.</span>, let's call this the 
-<code>User</code> class.
+ <code>User</code> class.
 </p>
 
 <pre class="python">
@@ -134 +134 @@
 </pre>
 
 <p>Again, assume that each remote client gets access to a single 
-<code>User</code> object, which is created with the proper username.</p>
+ <code>User</code> object, which is created with the proper username.</p>
 
 <p>Note how the <code>ChatServer</code> object has no remote access: it
 isn't even <code>pb.Referenceable</code> anymore. This means that all access
@@ -143 +143 @@
 
 <p>As long as Alice only has access to her own <code>User</code> object, she
 can no longer spoof Bob. The only way for her to invoke 
-<code>ChatServer.sendMessage</code> is to call her <code>User</code>
+ <code>ChatServer.sendMessage</code> is to call her <code>User</code>
 object's <code>remote_sendMessage</code> method, and that method uses its
 own state to provide the <code>from_username</code> argument. It doesn't
 give her any way to change that state.</p>
@@ -151 +151 @@
 <p>This restriction is important. The <code>User</code> object is able to
 maintain its own integrity because there is a wall between the object and
 the client: the client cannot inspect or modify internal state, like the 
-<code>.name</code> attribute. The only way through this wall is via remote
+ <code>.name</code> attribute. The only way through this wall is via remote
 method invocations, and the only control Alice has over those invocations is
 when they get invoked and what arguments they are given.</p>
 
@@ -170 +170 @@
 sensitive and calming them down after someone said <q>mattress</q> is a
 hassle that's best avoided altogether. Again, per-group state implies a
 per-group object. We'll go out on a limb and call this the 
-<code>Group</code> object:</p>
+ <code>Group</code> object:</p>
 
 <pre class="python">
 class User(pb.Referenceable):
@@ -208 +208 @@
 
 
 <p>This example takes advantage of the fact that 
-<code>pb.Referenceable</code> objects sent over a wire can be returned to
+ <code>pb.Referenceable</code> objects sent over a wire can be returned to
 you, and they will be turned into references to the same object that you
 originally sent. The client cannot modify the object in any way: all they
 can do is point at it and invoke its <code>remote_*</code> methods. Thus,
@@ -232 +232 @@
 into a <code>pb.RemoteReference</code> when it arrives at the client. The
 client sends it back to <code>Group.remote_send</code>, and PB turns it back
 into a reference to the original <code>User</code> when it gets there. 
-<code>Group.remote_send</code> can then use its <code>.name</code> attribute
+ <code>Group.remote_send</code> can then use its <code>.name</code> attribute
 as the sender of the message.</p>
 
 <div class="note">
@@ -240 +240 @@
 <p>Third party references (there aren't any)</p>
 
 <p>This technique also relies upon the fact that the 
-<code>pb.Referenceable</code> reference can <em>only</em> come from someone
+ <code>pb.Referenceable</code> reference can <em>only</em> come from someone
 who holds a corresponding <code>pb.RemoteReference</code>. The design of the
 serialization mechanism (implemented in <code
 class="API">twisted.spread.jelly</code>: pb, jelly, spread.. get it?  Look for 
@@ -254 +254 @@
 dropped, further limiting the scope of those references.</p>
 
 <p>Futhermore, it is not possible for Bob to send <em>his</em> 
-<code>User</code> reference to Alice (perhaps over some other PB channel
+ <code>User</code> reference to Alice (perhaps over some other PB channel
 just between the two of them). Outside the context of Bob's connection to
 the server, that reference is just a meaningless number. To prevent
 confusion, PB will tell you if you try to give it away: when you try to hand
@@ -287 +287 @@
 
 
 <p>But again, note the vulnerability. If Alice holds a 
-<code>RemoteReference</code> to <em>any</em> object on the server side that
+ <code>RemoteReference</code> to <em>any</em> object on the server side that
 has a <code>.name</code> attribute, she can use that name as a spoofed
 <q>from</q> parameter. As a simple example, what if her client code looked
 like:</p>
@@ -314 +314 @@
 
 <p>There are two techniques to close this hole. The first is to have your
 remotely-invokable methods do type-checking on their arguments: if 
-<code>Group.remote_send</code> asserted <code>isinstance(from_user,
+ <code>Group.remote_send</code> asserted <code>isinstance(from_user,
 User)</code> then Alice couldn't use non-User objects to do her spoofing,
 and hopefully the rest of the system is designed well enough to prevent her
 from obtaining access to somebody else's User object.</p>
@@ -325 +325 @@
 <p>The second technique is to avoid having the client send you the objects
 altogether. If they don't send you anything, there is nothing to verify. In
 this case, you would have to have a per-user-per-group object, in which the 
-<code>remote_send</code> method would only take a single 
-<code>message</code> argument. The <code>UserGroup</code> object is created
+ <code>remote_send</code> method would only take a single 
+ <code>message</code> argument. The <code>UserGroup</code> object is created
 with references to the only <code>User</code> and <code>Group</code> objects
 that it will ever use, so no lookups are needed:</p>
 
@@ -353 +353 @@
 </pre>
 
 <p>The only message-sending method Alice has left is 
-<code>UserGroup.remote_send</code>, and it only accepts a message: there are
+ <code>UserGroup.remote_send</code>, and it only accepts a message: there are
 no remaining ways to influence the <q>from</q> name.</p>
 
 <p>In this model, each remotely-accessible object represents a very small
@@ -361 +361 @@
 abilities to each remote user.</p>
 
 <p>PB provides a shortcut which makes this technique easier to use. The 
-<code>Viewable</code> class will be discussed <a
+ <code>Viewable</code> class will be discussed <a
 href="#viewable">below</a>.</p>
 
 <h2>Avatars and Perspectives</h2>
@@ -382 +382 @@
 
 <p>For PB, the first question is easy. The Avatar is a remotely-accessible
 object which can run code: this is a perfect description of 
-<code>pb.Referenceable</code> and its subclasses. We shall defer the second
+ <code>pb.Referenceable</code> and its subclasses. We shall defer the second
 question until the next section.</p>
 
 <p>In the example above, you can think of the <code>ChatServer</code> and 
-<code>Group</code> objects as a service. The <code>User</code> object is the
+ <code>Group</code> objects as a service. The <code>User</code> object is the
 user's server-side representative: everything the user is capable of doing
 is done by running one of its methods. Anything that the server wants to do
 to the user (change their group membership, change their name, delete their
@@ -401 +401 @@
 provides and controls (i.e. <q>brokers</q>) access to Perspectives.</p>
 
 <p>Once upon a time, these local-representative objects were actually called 
-<code>pb.Perspective</code>. But this has changed with the advent of the
+ <code>pb.Perspective</code>. But this has changed with the advent of the
 rewritten cred system, and now the more generic term for a local
 representative object is an Avatar. But you will still see reference to 
 <q>Perspective</q> in the code, the docs, and the module names<span
 class="footnote">We could just go ahead and rename Perspective Broker to be
 Avatar Broker, but 1) that would cause massive compatibility problems, and 2) 
-<q>AB</q> doesn't fit into the whole sandwich-themed naming scheme nearly as
+ <q>AB</q> doesn't fit into the whole sandwich-themed naming scheme nearly as
 well as <q>PB</q> does. If we changed it to AB, we'd probably have to change
 Banana to be CD (CoderDecoder), and Jelly to be EF (EncapsulatorFragmentor).
 twisted.spread would then have to be renamed twisted.alphabetsoup, and then
@@ -417 +417 @@
 <p>Despite all we've been <a href="cred.xhtml">telling you</a> about how
 Avatars are more of a concept than an actual class, the base class from
 which you can create your server-side avatar-ish objects is, in fact, named 
-<code>pb.Avatar</code><span class="footnote">The avatar-ish class is named 
-<code>pb.Avatar</code> because <code>pb.Perspective</code> was already
+ <code>pb.Avatar</code><span class="footnote">The avatar-ish class is named 
+ <code>pb.Avatar</code> because <code>pb.Perspective</code> was already
 taken, by the (now obsolete) oldcred perspective-ish class. It is a pity,
 but it simply wasn't possible both replace <code>pb.Perspective</code>
 in-place <em>and</em> maintain a reasonable level of
 backwards-compatibility.</span>. These objects behave very much like 
-<code>pb.Referenceable</code>. The only difference is that instead of
+ <code>pb.Referenceable</code>. The only difference is that instead of
 offering <q>remote_FOO</q> methods, they offer <q>perspective_FOO</q>
 methods.</p>
 
 <p>The other way in which <code>pb.Avatar</code> differs from 
-<code>pb.Referenceable</code> is that the avatar objects are designed to be
+ <code>pb.Referenceable</code> is that the avatar objects are designed to be
 the first thing retrieved by a cred-using remote client. Just as 
-<code>PBClientFactory.getRootObject</code> gives the client access to a 
-<code>pb.Root</code> object (which can then provide access to all kinds of
+ <code>PBClientFactory.getRootObject</code> gives the client access to a 
+ <code>pb.Root</code> object (which can then provide access to all kinds of
 other objects), <code>PBClientFactory.login</code> gives client access to a 
-<code>pb.Avatar</code> object (which can return other references). </p>
+ <code>pb.Avatar</code> object (which can return other references). </p>
 
 <p>So, the first half of using cred in your PB application is to create an
 Avatar object which implements <code>perspective_</code> methods and is
@@ -491 +491 @@
 they can provide it with an optional <code>client</code> argument (which
 must be a <code>pb.Referenceable</code> object). If they do, then a
 reference to that object will be handed to the realm's 
-<code>requestAvatar</code> in the <code>mind</code> argument.</p>
+ <code>requestAvatar</code> in the <code>mind</code> argument.</p>
 
 <p>The server-side Perspective can use it to invoke remote methods on
 something in the client, so that the client doesn't always have to drive the
@@ -523 +523 @@
 that is exposed to the remote client.</p>
 
 <p>Second, we created a realm (an object which implements 
-<code>IRealm</code>, and therefore implements <code>requestAvatar</code>).
+ <code>IRealm</code>, and therefore implements <code>requestAvatar</code>).
 This realm manufactures <code>MyPerspective</code> objects. It makes as many
 as we want, and names each one with the avatarID (a username) that comes out
 of the checkers. This MyRealm object returns two other objects as well,
@@ -534 +534 @@
 Avatars for any which survive the authentication process.</p>
 
 <p>Fourth, we made a simple checker (an object which implements 
-<code>IChecker</code>) to hold valid user/password pairs. The checker
+ <code>IChecker</code>) to hold valid user/password pairs. The checker
 gets registered with the portal, so it knows who to ask when new
 clients connect.  We use a checker named 
-<code>InMemoryUsernamePasswordDatabaseDontUse</code>, which suggests
+ <code>InMemoryUsernamePasswordDatabaseDontUse</code>, which suggests
 that 1: all the username/password pairs are kept in memory instead of
 being saved to a database or something, and 2: you shouldn't use
 it. The admonition against using it is because there are better
@@ -558 +558 @@
 href="pb-usage.xhtml">before</a>) and attached to a TCP connection. When the
 connection completes, the factory will be asked to produce a Protocol, and
 it will create a PB object. Unlike the previous chapter, where we used 
-<code>.getRootObject</code>, here we use <code>factory.login</code> to
-initiate the cred authentication process. We provide a 
-<code>credentials</code> object, which is the client-side agent for doing
+ <code>.getRootObject</code>, here we use <code>factory.login</code> to
+ initiate the cred authentication process. We provide a 
+ <code>credentials</code> object, which is the client-side agent for doing
 our half of the authentication process. This process may involve several
 messages: challenges, responses, encrypted passwords, secure hashes, etc. We
 give our credentials object everything it will need to respond correctly (in
@@ -568 +568 @@
 used public-key encryption or even fancier techniques).</p>
 
 <p><code>login</code> returns a Deferred which, when it fires, will return a 
-<code>pb.RemoteReference</code> to the remote avatar. We can then do 
-<code>callRemote</code> to invoke a <code>perspective_foo</code> method on
+ <code>pb.RemoteReference</code> to the remote avatar. We can then do 
+ <code>callRemote</code> to invoke a <code>perspective_foo</code> method on
 that Avatar.</p>
 
 
@@ -580 +580 @@
 
 <p>pbAnonServer.py implements a server based on pb6server.py, extending it to
 permit anonymous logins in addition to authenticated logins. An 
-<code class="API" base="twisted.cred.checkers">AllowAnonymousAccess</code>
+ <code class="API" base="twisted.cred.checkers">AllowAnonymousAccess</code>
 checker and an <code class="API"
 base="twisted.cred.checkers">InMemoryUsernamePasswordDatabaseDontUse</code>
 checker are registered and the
 client's choice of credentials object determines which is used to authenticate
 the login.  In either case, the realm will be called on to create an avatar for
 the login.  <code>AllowAnonymousAccess</code> always produces an <code>avatarId
-</code> of <code>twisted.cred.checkers.ANONYMOUS</code>.</p>
+ </code> of <code>twisted.cred.checkers.ANONYMOUS</code>.</p>
 
 <p>On the client side, the only change is the use of an instance of 
-<code class="API" base="twisted.cred.credentials">Anonymous</code> when calling 
-<code class="API" base="twisted.spread.pb">PBClientFactory.login</code>.</p>
+ <code class="API" base="twisted.cred.credentials">Anonymous</code> when calling 
+ <code class="API" base="twisted.spread.pb">PBClientFactory.login</code>.</p>
 
 
 <h2>Using Avatars</h2>
@@ -621 +621 @@
 <h3>Making Avatars</h3>
 
 <p>In the example above, we create Avatars upon request, during 
-<code>requestAvatar</code>. Depending upon the service, these Avatars might
+ <code>requestAvatar</code>. Depending upon the service, these Avatars might
 already exist before the connection is received, and might outlive the
 connection. The Avatars might also accept multiple connections.</p>
 
@@ -633 +633 @@
 Avatar later, once the lookup had completed.</p>
 
 <p>Here are some possible implementations of 
-<code>MyRealm.requestAvatar</code>:</p>
+ <code>MyRealm.requestAvatar</code>:</p>
 
 <pre class="python">
     # pre-existing, static avatars
@@ -695 +695 @@
 avatar that a remote client has just attached. The Realm can also ask the
 protocol to let it know when the connection goes away, so it can then inform
 the Avatar that the client has detached. The third member of the 
-<code>requestAvatar</code> return tuple is a callable which will be invoked
+ <code>requestAvatar</code> return tuple is a callable which will be invoked
 when the connection is lost.</p>
 
 <pre class="python">
@@ -727 +727 @@
 represent users, the <code class="API"
 base="twisted.spread.flavors">Viewable</code> class can come into play. This
 class behaves a lot like <code>Referenceable</code>: it turns into a 
-<code>RemoteReference</code> when sent over the wire, and certain methods
+ <code>RemoteReference</code> when sent over the wire, and certain methods
 can be invoked by the holder of that reference. However, the methods that
-can be called have names that start with <code>view_</code> instead of 
-<code>remote_</code>, and those methods are always called with an extra 
+can be called have names that start with <code>view_</code> instead of  <code>remote_</code>, and those methods are always called with an extra 
 <code>perspective</code> argument that points to the Avatar through which
 the reference was sent:</p>
 
@@ -751 +750 @@
 just have per-group objects which inherit from <code>pb.Viewable</code>, and
 give the user references to them. The local <code>pb.Avatar</code> object
 will automatically show up as the <q>perspective</q> argument in the 
-<code>view_*</code> method calls, give you a chance to involve the Avatar in
+ <code>view_*</code> method calls, give you a chance to involve the Avatar in
 the process.</p>
 
 
@@ -767 +766 @@
 
 <p>Notice that the client uses <code>perspective_joinGroup</code> to both
 join a group and retrieve a <code>RemoteReference</code> to the 
-<code>Group</code> object. However, the reference they get is actually to a
+ <code>Group</code> object. However, the reference they get is actually to a
 special intermediate object called a <code>pb.ViewPoint</code>. When they do 
-<code>group.callRemote("send", "message")</code>, their avatar is inserted
+ <code>group.callRemote("send", "message")</code>, their avatar is inserted
 into the argument list that <code>Group.view_send</code> actually sees. This
 lets the group get their username out of the Avatar without giving the
 client an opportunity to spoof someone else.</p>

doc/core/howto/testing.xhtml

@@ -72 +72 @@
 The <code>tearDown</code> method is a good place to put cleanup code: it is
 always run regardless of whether your test passes or fails (like a bare <code>
 except</code> clause in a try-except construct). Exceptions in <code>tearDown
-</code> are flagged as errors and flunk the test. 
-<code class="API" base="twisted.trial.unittest">TestCase.addCleanup</code> is
+ </code> are flagged as errors and flunk the test. 
+ <code class="API" base="twisted.trial.unittest">TestCase.addCleanup</code> is
 another useful tool for cleaning up.  With it, you can register callables to
 clean up resources as the test allocates them.  Generally, code should be
 written so that only resources allocated in the tests need to be cleaned up in
@@ -84 +84 @@
 return a Deferred from your test method, setUp, or tearDown and Trial will
 do the right thing. That is, it will run the reactor for you until the
 Deferred has triggered and its callbacks have been run. Don't use 
-<code>reactor.run()</code>, <code>reactor.stop()</code>, <code>reactor.crash()</code> or <code>reactor.iterate()</code> in your tests.</p>
+ <code>reactor.run()</code>, <code>reactor.stop()</code>, <code>reactor.crash()</code> or <code>reactor.iterate()</code> in your tests.</p>
 
 <p>Calls to <code>reactor.callLater</code> create <code class="API"
 base="twisted.internet.interfaces">IDelayedCall</code>s.  These need to be run
@@ -132 +132 @@
 <h3>Interacting with warnings in tests</h3>
 
 <p>Trial includes specific support for interacting with Python's 
-<code>warnings</code> module.  This support allows warning-emitting code to
+ <code>warnings</code> module.  This support allows warning-emitting code to
 be written test-driven, just as any other code would be.  It also improves
 the way in which warnings reporting when a test suite is running.</p>
 
@@ -140 +140 @@
 class="API" base="twisted.trial.unittest">TestCase.flushWarnings</code>
 allows tests to be written which make assertions about what warnings have
 been emitted during a particular test method. In order to test a warning with 
-<code>flushWarnings</code>, write a test which first invokes the code which
+ <code>flushWarnings</code>, write a test which first invokes the code which
 will emit a warning and then calls <code>flushWarnings</code> and makes
 assertions about the result.  For example:</p>
 
@@ -161 +161 @@
 method, it will not raise an exception when warnings have been configured as
 errors.  However, if called outside of a test method (for example, at module
 scope in a test module or a module imported by a test module) then it 
-<em>will</em> raise an exception.</p>
+ <em>will</em> raise an exception.</p>
 
   </body>
 </html>

doc/core/howto/gendefer.xhtml

@@ -120 +120 @@
 d.addCallback(printNumber)
 </pre>
 
-<p>You will notice that despite creating a Deferred in the 
-<code>largeFibonnaciNumber</code> function, these things happened:</p>
+<p>You will notice that despite creating a Deferred in the  <code>largeFibonnaciNumber</code> function, these things happened:</p>
 <ul>
 <li>the &quot;Total time taken for largeFibonnaciNumber call&quot; output
 shows that the function did not return immediately as asynchronous functions
@@ -286 +285 @@
 
 <h3>Firing Deferreds more than once is impossible</h3>
 
-<p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or 
-<code>Deferred.errback</code> once. The processing chain continues each time
+<p>Deferreds are one-shot. You can only call <code>Deferred.callback</code> or <code>Deferred.errback</code> once. The processing chain continues each time
 you add new callbacks to an already-called-back-to Deferred.</p>
 
 <h3>Synchronous callback execution</h3>
 
-<p>If a Deferred already has a result available, <code>addCallback</code> 
-<strong>may</strong> call the callback synchronously: that is, immediately
+<p>If a Deferred already has a result available, <code>addCallback</code> <strong>may</strong> call the callback synchronously: that is, immediately
 after it's been added.  In situations where callbacks modify state, it is
 might be desirable for the chain of processing to halt until all callbacks are
 added. For this, it is possible to <code>pause</code> and <code>unpause</code>
@@ -301 +298 @@
 
 <p>Be careful when you use these methods! If you <code>pause</code> a
 Deferred, it is <em>your</em> responsibility to make sure that you unpause it.
-The function adding the callbacks must unpause a paused Deferred, it should 
-<em>never</em> be the responsibility of the code that actually fires the
+The function adding the callbacks must unpause a paused Deferred, it should <em>never</em> be the responsibility of the code that actually fires the
 callback chain by calling <code>callback</code> or <code>errback</code> as
 this would negate its usefulness!</p>
 

doc/core/howto/telnet.xhtml

@@ -58 +58 @@
 
 <p>The service object is the service used to serve the telnet shell,
 and that it is listening on port 4040 with something called a 
-<code class="API" base="twisted.manhole.telnet">ShellFactory</code>. 
+ <code class="API" base="twisted.manhole.telnet">ShellFactory</code>. 
 Its parent is a <code class="python">twisted.application.service.MultiService</code>,
 a collection of services. We can keep getting the parent attribute
 of services until we hit the root of all services.</p>
@@ -67 +67 @@
 running process, see the internal objects, and even change
 their attributes. The telnet server can of course be used from straight 
 Python code; you can see how to do this by reading the code for 
-<code class="API">twisted.tap.telnet</code>.</p>
+ <code class="API">twisted.tap.telnet</code>.</p>
 
 <p>A final note - if you want access to be more secure, you can even
 have the telnet server use SSL. Assuming you have the appropriate

doc/core/howto/pb-limits.xhtml

@@ -32 +32 @@
 
   <p>Another limit imposed by Twisted's Banana implementation is a limit on
 the size of long integers.  The purpose of this limit is the same as the 
-<code>SIZE_LIMIT</code>.  By default, only integers between -2 ** 448 and 2
+ <code>SIZE_LIMIT</code>.  By default, only integers between -2 ** 448 and 2
 ** 448 (exclusive) can be transferred.  This limit can be changed using 
-<code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
+ <code class="API">twisted.spread.banana.setPrefixLimit</code>.</p>
 
   <h2>Perspective Broker Limits</h2>
 

doc/core/howto/dirdbm.xhtml

@@ -45 +45 @@
 can transparently persist
 them. <code>Shelf</code> works exactly like <code>DirDBM</code>, except that
 the values (but not the keys) can be arbitrary picklable objects. However,
-notice that mutating an object after it has been stored in the 
-<code>Shelf</code> has no effect on the Shelf.
+notice that mutating an object after it has been stored in the  <code>Shelf</code> has no effect on the Shelf.
 When mutating objects, it is neccessary to explictly store them back in the <code>Shelf</code>
 afterwards:</p>
 

doc/core/howto/pb-usage.xhtml

@@ -11 +11 @@
 
 <p>The first example to look at is a complete (although somewhat trivial)
 application. It uses <code>PBServerFactory()</code> on the server side, and 
-<code>PBClientFactory()</code> on the client side.</p>
+ <code>PBClientFactory()</code> on the client side.</p>
 
 <a href="../examples/pbsimple.py" class="py-listing" skipLines="5"
 >pbsimple.py</a>
@@ -19 +19 @@
 >pbsimpleclient.py</a>
 
 <p>First we look at the server. This defines an Echoer class (derived from 
-<code class="API" base="twisted.spread">pb.Root</code>), with a method called 
-<code>remote_echo()</code>. 
-<code class="API" base="twisted.spread">pb.Root</code> objects (because of
+ <code class="API" base="twisted.spread">pb.Root</code>), with a method called 
+ <code>remote_echo()</code>. 
+ <code class="API" base="twisted.spread">pb.Root</code> objects (because of
 their inheritance of 
-<code class="API" base="twisted.spread">pb.Referenceable</code>, described
+ <code class="API" base="twisted.spread">pb.Referenceable</code>, described
 later) can define methods with names of the form <code>remote_*</code>; a
 client which obtains a remote reference to that 
-<code class="API" base="twisted.spread">pb.Root</code> object will be able to
+ <code class="API" base="twisted.spread">pb.Root</code> object will be able to
 invoke those methods.</p>
 
 <p>The <code class="API" base="twisted.spread">pb.Root</code>-ish object is
 given to a <code class="API"
 base="twisted.spread">pb.PBServerFactory</code><code>()</code>. This is a 
-<code class="API" base="twisted.internet.protocol">Factory</code> object like
+ <code class="API" base="twisted.internet.protocol">Factory</code> object like
 any other: the <code class="API"
 base="twisted.internet.protocol">Protocol</code> objects it creates for new
 connections know how to speak the PB protocol. The object you give to 
-<code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which
+ <code>pb.PBServerFactory()</code> becomes the <q>root object</q>, which
 simply makes it available for the client to retrieve. The client may only
 request references to the objects you want to provide it: this helps you
 implement your security model. Because it is so common to export just a
@@ -47 +47 @@
 the client retrieves it.</p>
 
 <p>The client side uses 
-<code class="API" base="twisted.spread">pb.PBClientFactory</code> to make a
+ <code class="API" base="twisted.spread">pb.PBClientFactory</code> to make a
 connection to a given port. This is a two-step process involving opening
 a TCP connection to a given host and port and requesting the root object
 using <code>.getRootObject()</code>.</p>
@@ -62 +62 @@
 obtained, this callback is run. The first argument passed to the
 callback is a remote reference to the distant root object.  (you can
 give other arguments to the callback too, see the other parameters for 
-<code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
+ <code>.addCallback()</code> and <code>.addCallbacks()</code>).</p>
 
 <p>The callback does:</p>
 
@@ -72 +72 @@
 
 <p>which causes the server's <code>.remote_echo()</code> method to be invoked.
 (running <code>.callRemote("boom")</code> would cause 
-<code>.remote_boom()</code> to be run, etc). Again because of the delay
+ <code>.remote_boom()</code> to be run, etc). Again because of the delay
 involved, <code>callRemote()</code> returns a 
-<code class="API" base="twisted.internet.defer">Deferred</code>. Assuming the
+ <code class="API" base="twisted.internet.defer">Deferred</code>. Assuming the
 remote method was run without causing an exception (including an attempt to
 invoke an unknown method), the callback attached to that 
-<code class="API" base="twisted.internet.defer">Deferred</code> will be
+ <code class="API" base="twisted.internet.defer">Deferred</code> will be
 invoked with any objects that were returned by the remote method call.</p>
 
 <p>In this example, the server's <code>Echoer</code> object has a method
@@ -101 +101 @@
 Deferreds turns out to be a very clean way to deal with the whole thing.</p>
 
 <p>The remote reference object (the one given to 
-<code>getRootObject()</code>'s success callback) is an instance the <code
+ <code>getRootObject()</code>'s success callback) is an instance the <code
 class="API" base="twisted.spread.pb">RemoteReference</code> class. This means
 you can use it to invoke methods on the remote object that it refers to. Only
 instances of <code class="API"
 base="twisted.spread.pb">RemoteReference</code> are eligible for 
-<code>.callRemote()</code>. The <code class="API"
+ <code>.callRemote()</code>. The <code class="API"
 base="twisted.spread.pb">RemoteReference</code> object is the one that lives
 on the remote side (the client, in this case), not the local side (where the
 actual object is defined).</p>
@@ -114 +114 @@
 <p>In our example, the local object is that <code>Echoer()</code> instance,
 which inherits from <code class="API" base="twisted.spread">pb.Root</code>,
 which inherits from 
-<code class="API" base="twisted.spread">pb.Referenceable</code>. It is that 
-<code>Referenceable</code> class that makes the object eligible to be available
+ <code class="API" base="twisted.spread">pb.Referenceable</code>. It is that 
+ <code>Referenceable</code> class that makes the object eligible to be available
 for remote method calls<span class="footnote">There are a few other classes
 that can bestow this ability, but pb.Referenceable is the easiest to
 understand; see 'flavors' below for details on the others.</span>. If you have
@@ -129 +129 @@
 <code>remote_*</code> methods can do.</p>
 
 <p>Also note: the other classes like 
-<code class="API" base="twisted.spread.pb">Referenceable</code> allow access to
+ <code class="API" base="twisted.spread.pb">Referenceable</code> allow access to
 other methods, in particular <code>perspective_*</code> and <code>view_*</code>
 may be accessed.  Don't write local-only methods with these names, because then
 remote callers will be able to do more than you intended.</p>
 
 <p>Also also note: the other classes like 
-<code class="API" base="twisted.spread">pb.Copyable</code> <em>do</em> allow
+ <code class="API" base="twisted.spread">pb.Copyable</code> <em>do</em> allow
 access to attributes, but you control which ones they can see.</p>
 </div>
 
 <p>You don't have to be a 
-<code class="API" base="twisted.spread">pb.Root</code> to be remotely callable,
+ <code class="API" base="twisted.spread">pb.Root</code> to be remotely callable,
 but you do have to be 
-<code class="API" base="twisted.spread">pb.Referenceable</code>.  (Objects that
+ <code class="API" base="twisted.spread">pb.Referenceable</code>.  (Objects that
 inherit from <code class="API" base="twisted.spread">pb.Referenceable</code>
 but not from <code class="API" base="twisted.spread">pb.Root</code> can be
 remotely called, but only 
-<code class="API" base="twisted.spread">pb.Root</code>-ish objects can be given
+ <code class="API" base="twisted.spread">pb.Root</code>-ish objects can be given
 to the <code class="API" base="twisted.spread.pb">PBServerFactory</code>.)</p>
 
 <h2>Complete Example</h2>
@@ -167 +167 @@
 It returns a <code class="API"
 base="twisted.internet.defer">Deferred</code>, which will have its
 callback called when the reactor connects to the remote server and 
-<code class="API" base="twisted.spread">pb.PBClientFactory</code> gets the
+ <code class="API" base="twisted.spread">pb.PBClientFactory</code> gets the
 root, and have its <code class="python">errback</code> called when the
 object-connection fails for any reason, whether it was host lookup
 failure, connection refusal, or some server-side error.
@@ -199 +199 @@
 inherit from <code class="API" base="twisted.spread.pb">Referenceable</code>
 (or one of the other flavors). If you try to pass a non-Referenceable object
 (say, by returning one from a <code>remote_*</code> method), you'll get an 
-<code class="API" base="twisted.spread.jelly">InsecureJelly</code>
+ <code class="API" base="twisted.spread.jelly">InsecureJelly</code>
 exception<span class="footnote">This can be overridden, by subclassing one of
 the Serializable flavors and defining custom serialization code for your
 class. See <a href="pb-copyable.xhtml">Passing Complex Types</a> for
@@ -214 +214 @@
 reference identifiers and turns them into actual objects. You need to stay
 aware of where the object lives: if it is on your side, you do actual method
 calls. If it is on the other side, you do 
-<code>.callRemote()</code><span class="footnote">The binary nature of this
+ <code>.callRemote()</code><span class="footnote">The binary nature of this
 local vs. remote scheme works because you cannot give RemoteReferences to a
 third party. If you could, then your object A could go to B, B could give it to
 C, C might give it back to you, and you would be hard pressed to tell if the
@@ -281 +281 @@
 subclass by deriving it from <code class="API"
 base="twisted.spread">pb.Error</code>. When any remotely-invokable method
 (like <code>remote_*</code> or <code>perspective_*</code>) raises a 
-<code>pb.Error</code>-derived exception, a serialized form of that Exception
+ <code>pb.Error</code>-derived exception, a serialized form of that Exception
 object will be sent back over the wire<span class="footnote">To be precise,
 the Failure will be sent if <em>any</em> exception is raised, not just
 pb.Error-derived ones. But the server will print ugly error messages if you
@@ -303 +303 @@
 for remotely-thrown <code>Exception</code> objects. To extract the string that
 was put into the exception, use its <code>.getErrorMessage()</code> method.
 To get the type of the exception (as a string), look at its 
-<code>.type</code> attribute. The stack traceback is available too. The
+ <code>.type</code> attribute. The stack traceback is available too. The
 intent is to let the errback function get just as much information about the
 exception as Python's normal <code>try:</code> clauses do, even though the
 exception occurred in somebody else's memory space at some unknown time in
@@ -325 +325 @@
 that <em>isn't</em> subclassed from <code>pb.Error</code>? Well, those are
 called <q>unexpected exceptions</q>, which make Twisted think that something
 has <em>really</em> gone wrong. These will raise an exception on the 
-<em>server</em> side. This won't break the connection (the exception is
+ <em>server</em> side. This won't break the connection (the exception is
 trapped, just like most exceptions that occur in response to network
 traffic), but it will print out an unsightly stack trace on the server's
 stderr with a message that says <q>Peer Will Receive PB Traceback</q>, just
@@ -344 +344 @@
 class="API" base="twisted.internet.defer">Deferred</code>, then a remote
 exception will still send a <code>Failure</code> object back over, but it
 will get lodged in the <code>Deferred</code> with nowhere to go. When that 
-<code>Deferred</code> finally goes out of scope, the side that did 
-<code>callRemote</code> will emit a message about an <q>Unhandled error in
+ <code>Deferred</code> finally goes out of scope, the side that did 
+ <code>callRemote</code> will emit a message about an <q>Unhandled error in
 Deferred</q>, along with an ugly stack trace. It can't raise an exception at
 that point (after all, the <code>callRemote</code> that triggered the
 problem is long gone), but it will emit a traceback. So be a good programmer
@@ -358 +358 @@
 <p>To implement the equivalent of the Python try/except blocks (which can
 trap particular kinds of exceptions and pass others <q>up</q> to
 higher-level <code>try/except</code> blocks), you can use the 
-<code>.trap()</code> method in conjunction with multiple 
-<code>errback</code> handlers on the <code>Deferred</code>. Re-raising an
+ <code>.trap()</code> method in conjunction with multiple 
+ <code>errback</code> handlers on the <code>Deferred</code>. Re-raising an
 exception in an <code>errback</code> handler serves to pass that new
 exception to the next handler in the chain. The <code>trap</code> method is
 given a list of exceptions to look for, and will re-raise anything that
@@ -399 +399 @@
 SomeClass</code> to match a remote caller who claims to have an object of
 type <q>SomeClass</q> could have nasty consequences for some modules that do
 significant operations in their <code>__init__</code> methods (think 
-<code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even
+ <code>telnetlib.Telnet(host='localhost', port='chargen')</code>, or even
 more powerful classes that you have available in your server program).
 Allowing a remote entity to create arbitrary classes in your namespace is
 nearly equivalent to allowing them to run arbitrary code.</p>
@@ -410 +410 @@
 base="twisted.spread">jelly</code>). The easiest way to make it possible to
 copy entire class instances over the wire is to have them inherit from <code
 class="API" base="twisted.spread">pb.Copyable</code>, and then to use 
-<code>setUnjellyableForClass(remoteClass, localClass)</code> on the
+ <code>setUnjellyableForClass(remoteClass, localClass)</code> on the
 receiving side. See <a href="pb-copyable.xhtml">Passing Complex Types</a>
 for an example.</p></span>.</p>
 
@@ -420 +420 @@
 at the remote end, the exception is returned to the caller asynchronously,
 so an <code>errback</code> handler for the associated <code>Deferred</code>
 is run. That errback receives a <code>Failure</code> which wraps the 
-<code>InsecureJelly</code>.</p>
+ <code>InsecureJelly</code>.</p>
 
 
 <p>Remember that <code>trap</code> re-raises exceptions that it wasn't asked
 to look for. You can only check for one set of exceptions per errback
 handler: all others must be checked in a subsequent handler. 
-<code>check_MyException</code> shows how multiple kinds of exceptions can be
+ <code>check_MyException</code> shows how multiple kinds of exceptions can be
 checked in a single errback: give a list of exception types to 
-<code>trap</code>, and it will return the matching member. In this case, the
+ <code>trap</code>, and it will return the matching member. In this case, the
 kinds of exceptions we are checking for (<code>MyException</code> and 
-<code>MyOtherException</code>) may be raised by the remote end: they inherit
+ <code>MyOtherException</code>) may be raised by the remote end: they inherit
 from <code class="API" base="twisted.spread">pb.Error</code>.</p>
 
 <p>The handler can return <code>None</code> to terminate processing of the
@@ -438 +438 @@
 errback; if there is no callback then processing terminates). It is a good
 idea to put an errback that will catch everything (no <code>trap</code>
 tests, no possible chance of raising more exceptions, always returns 
-<code>None</code>) at the end of the chain. Just as with regular <code>try:
+ <code>None</code>) at the end of the chain. Just as with regular <code>try:
 except:</code> handlers, you need to think carefully about ways in which
 your errback handlers could themselves raise exceptions. The extra
 importance in an asynchronous environment is that an exception that falls
 off the end of the <code>Deferred</code> will not be signalled until that 
-<code>Deferred</code> goes out of scope, and at that point may only cause a
+ <code>Deferred</code> goes out of scope, and at that point may only cause a
 log message (which could even be thrown away if <code class="API"
 base="twisted.python">log.startLogging</code> is not used to point it at
 stdout or a log file). In contrast, a synchronous exception that is not

doc/core/howto/basics.xhtml

@@ -12 +12 @@
 
 <h2>Application</h2>
 
-<p>Twisted programs usually work with 
-<code class="API">twisted.application.service.Application</code>.
-This class usually holds all persistent configuration of
-a running server -- ports to bind to, places where connections
-to must be kept or attempted, periodic actions to do and almost
-everything else. It is the root object in a tree of services implementing 
-<code class="API" base="twisted.application.service">IService</code>.</p>
+<p>Twisted programs usually work
+with <code class="API">twisted.application.service.Application</code>.
+This class usually holds all persistent configuration of a running
+server -- ports to bind to, places where connections to must be kept
+or attempted, periodic actions to do and almost everything else. It is
+the root object in a tree of services implementing <code class="API"
+base="twisted.application.service">IService</code>.</p>
 
 <p>Other HOWTOs describe how to write custom code for Applications,
 but this one describes how to use already written code (which can be
@@ -34 +34 @@
 
 <p>The Twisted Daemon is a program that knows how to run Applications.
 This program
-is <code class="shell">twistd</code>.  Strictly
+is <code class="shell">twistd(1)</code>.  Strictly
 speaking, <code class="shell">twistd</code> is not necessary --
 fetching the application, getting the <code>IService</code> component,
 calling <code>startService</code>, scheduling <code>stopService</code> when
 the reactor shuts down, and then calling <code>reactor.run()</code> could be
-done manually. <code class="shell">twistd</code>, however, supplies 
+done manually. <code class="shell">twistd(1)</code>, however, supplies 
 many options which are highly useful for program set up.</p>
 
 <p><code class="shell">twistd</code> supports choosing a reactor (for more on
@@ -52 +52 @@
 object called <code>application</code> is used, use the <code class="shell">-y</code>
 option.</p>
 
-<p>When <code class="shell">twistd</code> runs, it records its process id in a 
-<code>twistd.pid</code> file (this can be configured via a command line
-switch). In order to shutdown the <code class="shell">twistd</code> process, kill that
-pid (usually you would do <code class="shell">kill `cat twistd.pid`</code>).
+<p>When <code class="shell">twistd</code> runs, it records its process
+id in a <code>twistd.pid</code> file (this can be configured via a
+command line switch). In order to shutdown
+the <code class="shell">twistd</code> process, kill that pid (usually
+you would do <code class="shell">kill `cat twistd.pid`</code>).
 </p>
 
 <p>As always, the gory details are in the manual page.</p>
@@ -63 +64 @@
 <h2>OS Integration</h2>
 
 <p>
-If you have an Application that runs with <code class="shell">twistd</code>,
-you can easily deploy it on RedHat Linux or Debian GNU/Linux based systems
-using the <code class="shell">tap2deb</code> or <code
-class="shell">tap2rpm</code> tools. These take a Twisted Application file (of
-any of the supported formats — Python source, XML or pickle), and build a
-Debian or RPM package (respectively) that installs the Application as a system
-service. The package includes the Application file, a default 
-<code>/etc/init.d/</code> script that starts and stops the process with twistd,
-and post-installation scripts that configure the Application to be run in the
-appropriate init levels.
+If you have an Application that runs
+with <code class="shell">twistd</code>, you can easily deploy it on
+RedHat Linux or Debian GNU/Linux based systems using
+the <code class="shell">tap2deb</code>
+or <code class="shell">tap2rpm</code> tools. These take a Twisted
+Application file (of any of the supported formats — Python source, XML
+or pickle), and build a Debian or RPM package (respectively) that
+installs the Application as a system service. The package includes the
+Application file, a default <code>/etc/init.d/</code> script that
+starts and stops the process with twistd, and post-installation
+scripts that configure the Application to be run in the appropriate
+init levels.
 </p>
 
 <!-- Is "note" really the right class to be using here? -->
-<div class="note">
-<code class="shell">tap2rpm</code> and <code class="shell">tap2deb</code> do
-not package your entire application and dependent code, just the Twisted
-Application file. You will need to find some other way to package your Python
-code, such as <code class="API">distutils</code>' <code>bdist_rpm</code>
-command.
+<div class="note"> <code class="shell">tap2rpm</code>
+and <code class="shell">tap2deb</code> do not package your entire
+application and dependent code, just the Twisted Application file. You
+will need to find some other way to package your Python code, such
+as <code class="API">distutils</code>' <code>bdist_rpm</code> command.
 </div>
 
 <p>

doc/core/howto/row.xhtml

@@ -187 +187 @@
 class="python">loadObjectsFrom</code> is called for a table, it will
 automatically load all the children rows for the rows from the specified
 table. The child rows will be put into a list member variable of the
-rowObject instance with the name <code>childRows</code> or if a 
-<em>containerMethod</em> is specified for the foreign key relationship,
+rowObject instance with the name <code>childRows</code> or if a <em>containerMethod</em> is specified for the foreign key relationship,
 that method will be called on the parent row object for each row that is
 being added to it as a child.</p>
 

doc/core/howto/design.xhtml

@@ -92 +92 @@
 <p> The <code class="python">QOTDFactory</code>'s role is to specify to the
 Twisted framework how to create a <code class="python">Protocol</code> instance
 that will handle the connection.  Twisted will not instantiate a <code
-class="python">QOTDFactory</code>; you will do that yourself later, in a
-<code class="shell">twistd</code> plug-in.
+class="python">QOTDFactory</code>; you will do that yourself later, in a <code class="shell">twistd</code> plug-in.
 </p>
 
-<p>Note: you can read more specifics of <code class="python">Protocol</code> and
-<code class="python">Factory</code> in the <a href="servers.xhtml">Writing
+<p>Note: you can read more specifics of <code class="python">Protocol</code> and <code class="python">Factory</code> in the <a href="servers.xhtml">Writing
 Servers</a> HOWTO.</p>
 
 <p>Once we have an abstraction -- a <code>Quoter</code> -- and we have a
 mechanism to connect it to the network -- the <code>QOTD</code> protocol -- the
 next thing to do is to put the last link in the chain of functionality between
-abstraction and user.  This last link will allow a user to choose a
-<code>Quoter</code> and configure the protocol. Writing this configuration is
+abstraction and user.  This last link will allow a user to choose a <code>Quoter</code> and configure the protocol. Writing this configuration is
 covered in the <a href="application.xhtml">Application HOWTO</a>.</p>
 
 </body>

doc/core/howto/process.xhtml

@@ -29 +29 @@
 and added to the reactor core so that the application will not block while
 sending data into or pulling data out of the new
 process. <code>reactor.spawnProcess</code> requires two arguments, 
-<code>processProtocol</code> and <code>executable</code>, and optionally takes
+ <code>processProtocol</code> and <code>executable</code>, and optionally takes
 several more: <code>args</code>, <code>environment</code>, 
-<code>path</code>, <code>userID</code>, <code>groupID</code>, 
-<code>usePTY</code>, and <code>childFDs</code>. Not all of these are
+ <code>path</code>, <code>userID</code>, <code>groupID</code>, 
+ <code>usePTY</code>, and <code>childFDs</code>. Not all of these are
 available on Windows.</p>
 
 
@@ -89 +89 @@
 
 <p><code>args</code> and <code>env</code> have empty default values, but
 many programs depend upon them to be set correctly. At the very least, 
-<code>args[0]</code> should probably be the same as <code>executable</code>.
+ <code>args[0]</code> should probably be the same as <code>executable</code>.
 If you just provide <code>os.environ</code> for <code>env</code>, the child
 program will inherit the environment from the current process, which is
 usually the civilized thing to do (unless you want to explicitly clean the
@@ -170 +170 @@
 <h2>Things that can happen to your ProcessProtocol</h2>
 
 <p>These are the methods that you can usefully override in your subclass of 
-<code>ProcessProtocol</code>:</p>
+ <code>ProcessProtocol</code>:</p>
 
 <ul>
 
@@ -386 +386 @@
 three fds, you need addtional methods to access those pipes. These methods
 are more generalized than the <code>.outReceived</code> ones described above.
 In fact, those methods (<code>outReceived</code> and 
-<code>errReceived</code>) are actually just wrappers left in for
+ <code>errReceived</code>) are actually just wrappers left in for
 compatibility with older code, written before this generalized fd mapping was
 implemented. The new list of things that can happen to your ProcessProtocol
 is as follows:</p>

doc/core/howto/quotes.xhtml

@@ -38 +38 @@
 </li>
 <li>Add the <code>TwistedQuotes</code> directory's <em>parent</em> to your Python
 path. For example, if the TwistedQuotes directory's path is
-<code>/tmp/TwistedQuotes</code>
+ <code>/tmp/TwistedQuotes</code>
 add <code>/tmp</code> to your Python path. On UNIX this would be <code
 class="shell">export PYTHONPATH=/my/stuff:$PYTHONPATH</code>, on Microsoft
 Windows change the <code class="shell">PYTHONPATH</code> variable through the

doc/core/howto/upgrading.xhtml

@@ -22 +22 @@
 <h2>Basic Persistence: Application and .tap files</h2>
 
 <p>Simple object persistence (using <code>pickle</code> or 
-<code>jelly</code>) provides the fundamental <q>save the object to disk</q>
+ <code>jelly</code>) provides the fundamental <q>save the object to disk</q>
 functionality at application shutdown. If you use the <code class="API"
 base="twisted.application.service">Application</code> object, every object
 referenced by your Application will be saved into the 
-<code>-shutdown.tap</code> file when the program terminates. When you use 
-<code>twistd</code> to launch that new .tap file, the Application object
+ <code>-shutdown.tap</code> file when the program terminates. When you use 
+ <code>twistd</code> to launch that new .tap file, the Application object
 will be restored along with all of its referenced data.</p>
 
 <p>This provides a simple way to have data outlive any particular invocation
@@ -35 +35 @@
 that all Services are referenced by the Application, so their attributes
 will be stored as well. Ports that have been bound with listenTCP (and the
 like) are also remembered, and the sockets are created at startup time (when 
-<code>Application.run</code> is called).</p>
+ <code>Application.run</code> is called).</p>
 
 <p>To influence the way that the <code class="API"
 base="twisted.application.service">Application</code> is persisted, you can adapt
@@ -46 +46 @@
 saved Application.</p>
 
 <p>You can manually cause the application to be saved by calling its 
-<code>.save</code> method (on the <code class="API">twisted.persisted.sob.IPersistable</code>
+ <code>.save</code> method (on the <code class="API">twisted.persisted.sob.IPersistable</code>
 adapted object).</p>
 
 
@@ -77 +77 @@
 </p>
 
 <p>The version number is defined in a class attribute named 
-<code>persistenceVersion</code>. This is an integer which will be stored in
+ <code>persistenceVersion</code>. This is an integer which will be stored in
 the .tap file along with the rest of the instance state. When the object is
 unserialized, the saved persistenceVersion is compared against the current
 class's value, and if they differ, special upgrade methods are called. These
@@ -138 +138 @@
 </pre>
 
 <p>Note that we must provide both <code>upgradeToVersion1</code>
-<em>and</em> <code>upgradeToVersion2</code>. We have to assume that the
+ <em>and</em> <code>upgradeToVersion2</code>. We have to assume that the
 saved .tap files which will be provided to this class come from a random
 assortment of old versions: we must be prepared to accept anything ever
 saved by a released version of our application.</p>
@@ -299 +299 @@
 mixed with <code class="API"
 base="twisted.persisted.styles">Versioned</code>. <code>rebuild</code> does
 not run any of the classes' methods, whereas <code>Versioned</code> works by
-running <code>__setstate__</code> during the load process and 
-<code>doUpgrade</code> afterwards. This means <code>rebuild</code> can only
+running <code>__setstate__</code> during the load process and  <code>doUpgrade</code> afterwards. This means <code>rebuild</code> can only
 be used to process upgrades that do not change the data attributes of any of
 the involved classes. Any time attributes are added or removed, the program
 must be shut down, persisted, and restarted, with <code>upgradeToVersionNN</code> methods