Ticket #4576: web.xhtml.patch

doc/web/howto/resource-templates.xhtml

@@ -12 +12 @@
 
 <h2>Overview</h2>
 
-<p>While high-level templating systems can be used with Twisted (for example,
-<a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod Nevow</a>, sometimes
-one needs a less file-heavy system which lets one directly write HTML. While
-ResourceScripts are available, they have a high overhead of coding, needing
-some boring string arithmetic. ResourceTemplates fill the space between Nevow
-and ResourceScript using Quixote's PTL (Python Templating Language).</p>
-
-<p>ResourceTemplates need Quixote installed. In 
-<a href="http://www.debian.org">Debian</a>, that means using Python 2.2
-and installing the <code>quixote</code> package 
-(<code>apt-get install quixote</code>). Other operating systems require
-other ways to install quixote, or it can be done manually.</p>
+<p>While high-level templating systems can be used with Twisted (for
+example, <a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod
+Nevow</a>, sometimes one needs a less file-heavy system which lets one
+directly write HTML. While ResourceScripts are available, they have a
+high overhead of coding, needing some boring string
+arithmetic. ResourceTemplates fill the space between Nevow and
+ResourceScript using Quixote's PTL (Python Templating Language).</p>
+
+<p>ResourceTemplates need Quixote
+installed. In <a href="http://www.debian.org">Debian</a>, that means
+using Python 2.2 and installing the <code>quixote</code> package
+(<code>apt-get install quixote</code>). Other operating systems
+require other ways to install quixote, or it can be done manually.</p>
 
 <h2>Configuring Twisted.Web</h2>
 
@@ -44 +45 @@
 
 <p>ResourceTemplates are coded in an extension of Python called the
 <q>Python Templating Language</q>. Complete documentation of the PTL
-is available at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the quixote web site</a>. The web server
-will expect the PTL source file to define a variable named
-<code>resource</code>.
-This should be a <code class="API">twisted.web.server.Resource</code>,
+is available
+at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the
+quixote web site</a>. The web server will expect the PTL source file
+to define a variable named <code>resource</code>.  This should be
+a <code class="API">twisted.web.server.Resource</code>,
 whose <code>.render</code> method be called. Usually, you would want
 to define <code>render</code> using the keyword <code>template</code>
 rather than <code>def</code>.</p>

doc/web/howto/using-twistedweb.xhtml

@@ -21 +21 @@
 
 <ul>
 
-<li><a href="#sites">Site Objects</a> are responsible for creating
-<code>HTTPChannel</code> instances to parse the HTTP request, and begin the object lookup process. They contain the root Resource, the resource which represents the URL <code>/</code> on the site.</li>
+<li><a href="#sites">Site Objects</a> are responsible for
+creating <code>HTTPChannel</code> instances to parse the HTTP request,
+and begin the object lookup process. They contain the root Resource,
+the resource which represents the URL <code>/</code> on the site.</li>
 
 <li><a href="#resources">Resource</a> objects represent a single URL segment. The <code class="API" base="twisted.web.resource">IResource</code> interface describes the methods a Resource object must implement in order to participate in the object publishing process.</li>
 
@@ -49 +51 @@
 
 <p>When using <code>twistd -n web --path /foo/bar/baz</code>, a Site object is created with a root Resource that serves files out of the given path.</p>
 
-<p>You can also create a <code>Site</code> instance by hand, passing it a
-<code>Resource</code> object which will serve as the root of the site:</p>
+<p>You can also create a <code>Site</code> instance by hand, passing
+it a <code>Resource</code> object which will serve as the root of the
+site:</p>
 
 <pre class="python">
 from twisted.web import server, resource
@@ -173 +176 @@
 
 The <code class="API" base="twisted.web.resource">Resource</code>
 class, which is usually what one's Resource classes subclass, has a
-convenient default implementation of <code
-class="python">render</code>. It will call a method named <code
-class="python">self.render_METHOD</code> where <q>METHOD</q> is
-whatever HTTP method was used to request this resource. Examples:
-request_GET, request_POST, request_HEAD, and so on. It is recommended
-that you have your resource classes subclass <code class="API"
-base="twisted.web.resource">Resource</code> and implement <code
-class="python">render_METHOD</code> methods as opposed to <code
-class="python">render</code> itself. Note that for certain resources,
-<code class="python">request_POST = request_GET</code> may be
-desirable in case one wants to process arguments passed to the
-resource regardless of whether they used GET
+convenient default implementation
+of <code class="python">render</code>. It will call a method
+named <code class="python">self.render_METHOD</code>
+where <q>METHOD</q> is whatever HTTP method was used to request this
+resource. Examples: request_GET, request_POST, request_HEAD, and so
+on. It is recommended that you have your resource classes
+subclass <code class="API" base="twisted.web.resource">Resource</code>
+and implement <code class="python">render_METHOD</code> methods as
+opposed to <code class="python">render</code> itself. Note that for
+certain resources, <code class="python">request_POST =
+request_GET</code> may be desirable in case one wants to process
+arguments passed to the resource regardless of whether they used GET
 (<code>?foo=bar&amp;baz=quux</code>, and so forth) or POST.
 
 </p>
@@ -201 +204 @@
 <h2>Advanced Configuration</h2>
 
 <p>Non-trivial configurations of Twisted Web are achieved with Python
-configuration files. This is a Python snippet which builds up a variable
-called application. Usually, a <code class="API">twisted.application.internet.TCPServer</code> instance will
-be used to make the application listen on a TCP port (80, in case direct
-web serving is desired), with the listener being a
-<code class="API">twisted.web.server.Site</code>. The resulting file can then
-be run with <code class="shell">twistd -y</code>. Alternatively a reactor
-object can be used directly to make a runnable script.</p>
+configuration files. This is a Python snippet which builds up a
+variable called application. Usually,
+a <code class="API">twisted.application.internet.TCPServer</code>
+instance will be used to make the application listen on a TCP port
+(80, in case direct web serving is desired), with the listener being
+a <code class="API">twisted.web.server.Site</code>. The resulting file
+can then be run with <code class="shell">twistd
+-y</code>. Alternatively a reactor object can be used directly to make
+a runnable script.</p>
 
 <p>The <code>Site</code> will wrap a <code>Resource</code> object -- the
 root.</p>
@@ -259 +264 @@
 
 <h3>Modifying File Resources</h3>
 
-<p><code>File</code> resources, be they root object or children thereof,
-have two important attributes that often need to be modified:
-<code>indexNames</code> and <code>processors</code>. <code>indexNames</code>
-determines which files are treated as <q>index files</q> -- served
-up when a directory is rendered. <code>processors</code> determine how
-certain file extensions are treated.</p>
+<p><code>File</code> resources, be they root object or children
+thereof, have two important attributes that often need to be
+modified: <code>indexNames</code>
+and <code>processors</code>. <code>indexNames</code> determines which
+files are treated as <q>index files</q> -- served up when a directory
+is rendered. <code>processors</code> determine how certain file
+extensions are treated.</p>
 
 <p>Here is an example for both, creating a site where all <code>.rpy</code>
 extensions are Resource Scripts, and which renders directories by
@@ -308 +314 @@
 
 <h3>Virtual Hosts</h3>
 
-<p>Virtual hosting is done via a special resource, that should be
-used as the root resource -- <code>NameVirtualHost</code>.
-<code>NameVirtualHost</code> has an attribute named <code>default</code>,
-which holds the default website. If a different root for some other
-name is desired, the <code>addHost</code> method should be called.</p>
+<p>Virtual hosting is done via a special resource, that should be used
+as the root resource
+-- <code>NameVirtualHost</code>. <code>NameVirtualHost</code> has an
+attribute named <code>default</code>, which holds the default
+website. If a different root for some other name is desired,
+the <code>addHost</code> method should be called.</p>
 
 <pre class="python">
 from twisted.application import internet, service
@@ -529 +536 @@
 
 <h3>Serving PHP/Perl/CGI</h3>
 
-<p>Everything related to CGI is located in the
-<code>twisted.web.twcgi</code>, and it's here you'll find the classes that you
-need to subclass in order to support the language of your (or somebody elses)
-taste. You'll also need to create your own kind of resource if you are using a
-non-unix operating system (such as Windows), or if the default resources has
-wrong pathnames to the parsers.</p>
+<p>Everything related to CGI is located in
+the <code>twisted.web.twcgi</code>, and it's here you'll find the
+classes that you need to subclass in order to support the language of
+your (or somebody elses) taste. You'll also need to create your own
+kind of resource if you are using a non-unix operating system (such as
+Windows), or if the default resources has wrong pathnames to the
+parsers.</p>
 
 <p>The following snippet is a .rpy that serves perl-files. Look at <code>twisted.web.twcgi</code>
 for more examples regarding twisted.web and CGI.</p>
@@ -643 +651 @@
 resource = vhost.VHostMonsterResource()
 </pre>
 
-<p>Make sure the web server is configured with the correct processors for the
-<code>rpy</code> extensions (the web server
-<code>twistd web --path</code> generates by default is so configured).</p>
+<p>Make sure the web server is configured with the correct processors
+for the <code>rpy</code> extensions (the web server <code>twistd web
+--path</code> generates by default is so configured).</p>
 
 <p>From the Apache side, instead of using the following ProxyPass directive:</p>
 
@@ -684 +692 @@
 
 <h2>Rewriting URLs</h2>
 
-<p>Sometimes it is convenient to modify the content of the
-<code class="API" base="twisted.web.server">Request</code> object
+<p>Sometimes it is convenient to modify the content of
+the <code class="API" base="twisted.web.server">Request</code> object
 before passing it on. Because this is most often used to rewrite
-either the URL, the similarity to Apache's <code>mod_rewrite</code> has
-inspired the <code class="API">twisted.web.rewrite</code> module. Using
-this module is done via wrapping a resource with a
-<code class="API">twisted.web.rewrite.RewriterResource</code> which
-then has rewrite rules. Rewrite rules are functions which accept a request
-object, and possible modify it. After all rewrite rules run, the child
-resolution chain continues as if the wrapped resource, rather than
-the <code class="API" base="twisted.web.rewrite">RewriterResource</code>,
-was the child.</p>
+either the URL, the similarity to Apache's <code>mod_rewrite</code>
+has inspired the <code class="API">twisted.web.rewrite</code>
+module. Using this module is done via wrapping a resource with
+a <code class="API">twisted.web.rewrite.RewriterResource</code> which
+then has rewrite rules. Rewrite rules are functions which accept a
+request object, and possible modify it. After all rewrite rules run,
+the child resolution chain continues as if the wrapped resource,
+rather than the <code class="API"
+base="twisted.web.rewrite">RewriterResource</code>, was the child.</p>
 
 <p>Here is an example, using the only rule currently supplied by Twisted
 itself:</p>
@@ -704 +712 @@
 default_root = rewrite.RewriterResource(default, rewrite.tildeToUsers)
 </pre>
 
-<p>This causes the URL <code>/~foo/bar.html</code> to be treated like
-<code>/users/foo/bar.html</code>. If done after setting default's
-<code>users</code> child to a
-<code class="API" base="twisted.web">distrib.UserDirectory</code>,
-it gives a configuration similar to the classical configuration of
-web server, common since the first NCSA servers.</p>
+<p>This causes the URL <code>/~foo/bar.html</code> to be treated
+like <code>/users/foo/bar.html</code>. If done after setting
+default's <code>users</code> child to a <code class="API"
+base="twisted.web">distrib.UserDirectory</code>, it gives a
+configuration similar to the classical configuration of web server,
+common since the first NCSA servers.</p>
 
 <h2>Knowing When We're Not Wanted</h2>
 
@@ -741 +749 @@
 
 <h2>As-Is Serving</h2>
 
-<p>Sometimes, you want to be able to send headers and status directly. While
-you can do this with a
-<code base="twisted.web.script" class="API">ResourceScript</code>, an easier
-way is to use <code base="twisted.web.static" class="API">ASISProcessor</code>.
-Use it by, for example, adding it as a processor for the <code>.asis</code>
-extension. Here is a sample file:</p>
+<p>Sometimes, you want to be able to send headers and status
+directly. While you can do this with a <code base="twisted.web.script"
+class="API">ResourceScript</code>, an easier way is to
+use <code base="twisted.web.static" class="API">ASISProcessor</code>.
+Use it by, for example, adding it as a processor for
+the <code>.asis</code> extension. Here is a sample file:</p>
 
 <pre>
 HTTP/1.0 200 OK

doc/web/howto/web-development.xhtml

@@ -82 +82 @@
 deployment with development, and makes sure your users will be <em>tied</em> to
 the file-system.</p>
 
-<p>We have <code>.rpy</code>s because they are useful and necessary.  But using
-them incorrectly leads to horribly unmaintainable applications.  The best way to
-ensure you are using them correctly is to not use them at all, until you are on
-your <em>final</em> deployment stages.  You should then find your
-<code>.rpy</code> files will be less than 10 lines, because you will not
-<em>have</em> more than 10 lines to write.</p>
+<p>We have <code>.rpy</code>s because they are useful and necessary.
+But using them incorrectly leads to horribly unmaintainable
+applications.  The best way to ensure you are using them correctly is
+to not use them at all, until you are on your <em>final</em>
+deployment stages.  You should then find your <code>.rpy</code> files
+will be less than 10 lines, because you will not <em>have</em> more
+than 10 lines to write.</p>
 
 </body>
 

doc/web/howto/xmlrpc.xhtml

@@ -99 +99 @@
 <h3>Using XML-RPC sub-handlers</h3>
 
 <p>XML-RPC resource can be nested so that one handler calls another if
-a method with a given prefix is called. For example, to add support for
-an XML-RPC method <code>date.time()</code> to the
-<code class="python">Example</code> class, you could do the following:</p>
+a method with a given prefix is called. For example, to add support
+for an XML-RPC method <code>date.time()</code> to
+the <code class="python">Example</code> class, you could do the
+following:</p>
 
 <pre class="python">
 import time
@@ -142 +143 @@
 
 <h3>Adding XML-RPC Introspection support</h3>
 
-<p>XML-RPC has an informal <a href="http://ldp.kernelnotes.de/HOWTO/XML-RPC-HOWTO/xmlrpc-howto-interfaces.html">Introspection API</a> that specifies three
-methods in a <code>system</code> sub-handler which allow a client to query
-a server about the server's API. Adding Introspection support to the
-<code class="python">Example</code> class is easy using the
-<code base="twisted.web.xmlrpc" class="API">XMLRPCIntrospection</code>
-class:</p>
+<p>XML-RPC has an
+informal <a href="http://ldp.kernelnotes.de/HOWTO/XML-RPC-HOWTO/xmlrpc-howto-interfaces.html">Introspection
+API</a> that specifies three methods in a <code>system</code>
+sub-handler which allow a client to query a server about the server's
+API. Adding Introspection support to
+the <code class="python">Example</code> class is easy using
+the <code base="twisted.web.xmlrpc"
+class="API">XMLRPCIntrospection</code> class:</p>
 
 <pre class="python">
 from twisted.web import xmlrpc, server
@@ -181 +184 @@
     reactor.run()
 </pre>
 
-<p>Note the method attributes <code class="python">help</code> and
-<code class="python">signature</code> which are used by the Introspection
-API methods <code>system.methodHelp</code> and
-<code>system.methodSignature</code> respectively. If no
-<code class="python">help</code> attribute is specified,
-the method's documentation string is used instead.</p>
+<p>Note the method attributes <code class="python">help</code>
+and <code class="python">signature</code> which are used by the
+Introspection API methods <code>system.methodHelp</code>
+and <code>system.methodSignature</code> respectively. If
+no <code class="python">help</code> attribute is specified, the
+method's documentation string is used instead.</p>
 
 <h2>SOAP Support</h2>
 
@@ -210 +213 @@
     <code>callRemote</code>.</li>
 </ol>
 
-<p>The interface Twisted presents to XML-RPC client is that of a proxy object:
-<code class="API">twisted.web.xmlrpc.Proxy</code>. The constructor for the
-object receives a URL: it must be an HTTP or HTTPS URL. When an XML-RPC service
-is described, the URL to that service will be given there.</p>
+<p>The interface Twisted presents to XML-RPC client is that of a proxy
+object: <code class="API">twisted.web.xmlrpc.Proxy</code>. The
+constructor for the object receives a URL: it must be an HTTP or HTTPS
+URL. When an XML-RPC service is described, the URL to that service
+will be given there.</p>
 
 <p>Having a proxy object, one can just call the <code>callRemote</code> method,
 which accepts a method name and a variable argument list (but no named
@@ -237 +241 @@
     print 'error', error
     reactor.stop()
 
-proxy = Proxy('http://advogato.org/XMLRPC')
+proxy = Proxy('http://advogato.oubunturg/XMLRPC')
 proxy.callRemote('test.sumprod', 3, 5).addCallbacks(printValue, printError)
 reactor.run()
 </pre>
@@ -257 +261 @@
 base="twisted.web.resource.IResource">putChild</code> method of Resources.</p>
 
 <p>The following example uses an empty <code class="API"
-base="twisted.web">resource.Resource</code> as the root resource for a <code
-class="API" base="twisted.web.server">Site</code>, and then adds
-<code>/RPC2</code> and <code>/SOAP</code> paths to it.</p>
+base="twisted.web">resource.Resource</code> as the root resource for
+a <code class="API" base="twisted.web.server">Site</code>, and then
+adds <code>/RPC2</code> and <code>/SOAP</code> paths to it.</p>
 
 <a href="listings/xmlAndSoapQuote.py" class="py-listing">xmlAndSoapQuote.py</a>
 
-<p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web
+<dh p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web
 Development</a> for more details about Resources.</p>
 
   </body>