Ticket #4569: tutorial.xhtml.patch

File tutorial.xhtml.patch, 6.7 KB (added by jdb, 4 years ago)
Line 
1diff --cc doc/core/howto/tutorial/intro.xhtml
2index b53c3ae,49101f7..0000000
3--- a/doc/core/howto/tutorial/intro.xhtml
4+++ b/doc/core/howto/tutorial/intro.xhtml
5@@@ -279,21 -286,21 +286,22 @@@ Configuration</a> file).</p
6 
7  <a href="listings/finger/finger11.tac" class="py-listing">finger11.tac</a>
8 
9- <p>Instead of using <code>reactor.listenTCP</code> as in the above examples,
10- here we are using its application-aware counterpart,
11- <code>internet.TCPServer</code>.  Notice that when it is instantiated, the
12- application object itself does not reference either the protocol or the factory.
13- Any services (such as <code>TCPServer</code>) which have the application as
14- their parent will be started when the application is started by twistd.  The
15- application object is more useful for returning an object that supports the
16- <code class="API"
17++
18+ <p>Instead of using <code>reactor.listenTCP</code> as in the above
19+ examples, here we are using its application-aware
20+ counterpart, <code>internet.TCPServer</code>.  Notice that when it is
21+ instantiated, the application object itself does not reference either
22+ the protocol or the factory.  Any services (such as TCPServer) which
23+ have the application as their parent will be started when the
24+ application is started by twistd.  The application object is more
25+ useful for returning an object that supports the <code class="API"
26  base="twisted.application.service">IService</code>, <code class="API"
27  base="twisted.application.service">IServiceCollection</code>, <code class="API"
28- base="twisted.application.service">IProcess</code>, and <code class="API"
29- base="twisted.persisted">sob.IPersistable</code> interfaces with the given
30- parameters; we'll be seeing these in the next part of the tutorial. As the
31- parent of the <code>TCPServer</code> we opened, the application lets us manage
32- the <code>TCPServer</code>.</p>
33+ base="twisted.application.service">IProcess</code>,
34+ and <code class="API" base="twisted.persisted">sob.IPersistable</code>
35+ interfaces with the given parameters; we'll be seeing these in the
36+ next part of the tutorial. As the parent of the TCPServer we opened,
37+ the application lets us manage the TCPServer.</p>
38 
39  <p>With the daemon running on the standard finger port, you can test it with
40  the standard finger command: <code>finger moshez</code>.</p>
41diff --cc doc/core/howto/tutorial/protocol.xhtml
42index 3fed88d,f6a98ab..0000000
43--- a/doc/core/howto/tutorial/protocol.xhtml
44+++ b/doc/core/howto/tutorial/protocol.xhtml
45@@@ -40,26 -40,27 +40,28 @@@ Giving a tutorial now, sorry
46 
47  <a href="listings/finger/finger12.tac" class="py-listing">finger12.tac</a>
48 
49- <p>This program has two protocol-factory-TCPServer pairs, which are both child
50- services of the application.  Specifically, the
51- <code base="API" class="twisted.application.service.Service">setServiceParent</code>
52- method is used to define the two TCPServer services as children of
53- <code>application</code>, which implements
54- <code base="API" class="twisted.application.servce">IServiceCollection</code>.
55- Both services are thus started with the application.</p>
56+ <p>This program has two protocol-factory-TCPServer pairs, which are
57+ both child services of the application.  Specifically,
58+ the <code base="API"
59+ class="twisted.application.service.Service">setServiceParent</code>
60+ method is used to define the two TCPServer services as children
61+ of <code>application</code>, which implements <code base="API"
62+ class="twisted.application.servce">IServiceCollection</code>.  Both
63+ services are thus started with the application.</p>
64+
65 +
66  <h2>Use Services to Make Dependencies Sane</h2>
67 
68  <p>The previous version had the setter poke at the innards of the
69  finger factory. This strategy is usually not a good idea: this version makes
70  both factories symmetric by making them both look at a single
71  object. Services are useful for when an object is needed which is
72 -not related to a specific network server. Here, we define a common service
73 -class with methods that will create factories on the fly. The service
74 +not related to a specific network server. Here, we define a common service
75 +class with methods that will create factories on the fly. The service
76  also contains methods the factories will depend on.</p>
77 
78- <p>The factory-creation methods, <code>getFingerFactory</code> and
79- <code>getFingerSetterFactory</code>, follow this pattern:</p>
80+ <p>The factory-creation methods, <code>getFingerFactory</code>
81+ and <code>getFingerSetterFactory</code>, follow this pattern:</p>
82 
83  <ol>
84 
85@@@ -69,24 -70,25 +71,26 @@@ factory, <code>twisted.internet.protoco
86  <li>Set the protocol class, just like our factory class would have.</li>
87 
88  <li>Copy a service method to the factory as a function attribute.  The
89- function won't have access to the factory's <code>self</code>, but that's OK
90- because as a bound method it has access to the service's <code>self</code>,
91- which is what it needs.  For <code>getUser</code>, a custom method defined in
92- the service gets copied.  For <code>setUser</code>, a standard method of the
93- <code>users</code> dictionary is copied.</li>
94+ function won't have access to the factory's <code>self</code>, but
95+ that's OK because as a bound method it has access to the
96+ service's <code>self</code>, which is what it needs.
97+ For <code>getUser</code>, a custom method defined in the service gets
98+ copied.  For <code>setUser</code>, a standard method of
99+ the <code>users</code> dictionary is copied.</li>
100+
101 +
102  </ol>
103 
104 -<p>Thus, we stopped subclassing: the service simply puts useful methods and
105 +<p>Thus, we stopped subclassing: the service simply puts useful methods and
106  attributes inside the factories. We are getting better at protocol design:
107 -none of our protocol classes had to be changed, and neither will have to
108 +none of our protocol classes had to be changed, and neither will have to
109  change until the end of the tutorial.</p>
110 
111- <p>As an application
112- <code class="API" base="twisted.application.service">Service</code> , this new
113- finger service implements the
114- <code class="API" base="twisted.application.service">IService</code> interface
115- and can be started and stopped in a standardized manner.  We'll make use of
116+ <p>As an application <code class="API"
117+ base="twisted.application.service">service</code> , this new finger
118+ service implements the <code class="API"
119+ base="twisted.application.service">IService</code> interface and can
120+ be started and stopped in a standardized manner.  We'll make use of
121  this in the next example.</p>
122 
123  <a href="listings/finger/finger13.tac" class="py-listing">finger13.tac</a>
124diff --cc doc/core/howto/tutorial/web.xhtml
125index 0efb9c3,9da8870..0000000
126--- a/doc/core/howto/tutorial/web.xhtml
127+++ b/doc/core/howto/tutorial/web.xhtml