Ticket #4576: web.xhtml.patch

File web.xhtml.patch, 20.0 KB (added by jdb, 4 years ago)

Adapted the lore input files so that no <code> or <em> tags are the first characters of a line. This fixes the rst and html final output.

  • doc/web/howto/resource-templates.xhtml

    diff --git a/doc/web/howto/resource-templates.xhtml b/doc/web/howto/resource-templates.xhtml
    index be7226a..b34d183 100644
    a b  
    1212 
    1313<h2>Overview</h2> 
    1414 
    15 <p>While high-level templating systems can be used with Twisted (for example, 
    16 <a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod Nevow</a>, sometimes 
    17 one needs a less file-heavy system which lets one directly write HTML. While 
    18 ResourceScripts are available, they have a high overhead of coding, needing 
    19 some boring string arithmetic. ResourceTemplates fill the space between Nevow 
    20 and ResourceScript using Quixote's PTL (Python Templating Language).</p> 
    21  
    22 <p>ResourceTemplates need Quixote installed. In  
    23 <a href="http://www.debian.org">Debian</a>, that means using Python 2.2 
    24 and installing the <code>quixote</code> package  
    25 (<code>apt-get install quixote</code>). Other operating systems require 
    26 other ways to install quixote, or it can be done manually.</p> 
     15<p>While high-level templating systems can be used with Twisted (for 
     16example, <a href="http://divmod.org/trac/wiki/DivmodNevow">Divmod 
     17Nevow</a>, sometimes one needs a less file-heavy system which lets one 
     18directly write HTML. While ResourceScripts are available, they have a 
     19high overhead of coding, needing some boring string 
     20arithmetic. ResourceTemplates fill the space between Nevow and 
     21ResourceScript using Quixote's PTL (Python Templating Language).</p> 
     22 
     23<p>ResourceTemplates need Quixote 
     24installed. In <a href="http://www.debian.org">Debian</a>, that means 
     25using Python 2.2 and installing the <code>quixote</code> package 
     26(<code>apt-get install quixote</code>). Other operating systems 
     27require other ways to install quixote, or it can be done manually.</p> 
    2728 
    2829<h2>Configuring Twisted.Web</h2> 
    2930 
    more Python coding and are outside the scope of this HOWTO.</p> 
    4445 
    4546<p>ResourceTemplates are coded in an extension of Python called the 
    4647<q>Python Templating Language</q>. Complete documentation of the PTL 
    47 is available at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the quixote web site</a>. The web server 
    48 will expect the PTL source file to define a variable named 
    49 <code>resource</code>. 
    50 This should be a <code class="API">twisted.web.server.Resource</code>, 
     48is available 
     49at <a href="http://www.mems-exchange.org/software/quixote/doc/PTL.html">the 
     50quixote web site</a>. The web server will expect the PTL source file 
     51to define a variable named <code>resource</code>.  This should be 
     52a <code class="API">twisted.web.server.Resource</code>, 
    5153whose <code>.render</code> method be called. Usually, you would want 
    5254to define <code>render</code> using the keyword <code>template</code> 
    5355rather than <code>def</code>.</p> 
  • doc/web/howto/using-twistedweb.xhtml

    diff --git a/doc/web/howto/using-twistedweb.xhtml b/doc/web/howto/using-twistedweb.xhtml
    index 5c4c388..b681a2c 100644
    a b IResource.</p> 
    2121 
    2222<ul> 
    2323 
    24 <li><a href="#sites">Site Objects</a> are responsible for creating 
    25 <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> 
     24<li><a href="#sites">Site Objects</a> are responsible for 
     25creating <code>HTTPChannel</code> instances to parse the HTTP request, 
     26and begin the object lookup process. They contain the root Resource, 
     27the resource which represents the URL <code>/</code> on the site.</li> 
    2628 
    2729<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> 
    2830 
    IResource.</p> 
    4951 
    5052<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> 
    5153 
    52 <p>You can also create a <code>Site</code> instance by hand, passing it a 
    53 <code>Resource</code> object which will serve as the root of the site:</p> 
     54<p>You can also create a <code>Site</code> instance by hand, passing 
     55it a <code>Resource</code> object which will serve as the root of the 
     56site:</p> 
    5457 
    5558<pre class="python"> 
    5659from twisted.web import server, resource 
    resource = myresource.MyResource() 
    173176 
    174177The <code class="API" base="twisted.web.resource">Resource</code> 
    175178class, which is usually what one's Resource classes subclass, has a 
    176 convenient default implementation of <code 
    177 class="python">render</code>. It will call a method named <code 
    178 class="python">self.render_METHOD</code> where <q>METHOD</q> is 
    179 whatever HTTP method was used to request this resource. Examples: 
    180 request_GET, request_POST, request_HEAD, and so on. It is recommended 
    181 that you have your resource classes subclass <code class="API" 
    182 base="twisted.web.resource">Resource</code> and implement <code 
    183 class="python">render_METHOD</code> methods as opposed to <code 
    184 class="python">render</code> itself. Note that for certain resources, 
    185 <code class="python">request_POST = request_GET</code> may be 
    186 desirable in case one wants to process arguments passed to the 
    187 resource regardless of whether they used GET 
     179convenient default implementation 
     180of <code class="python">render</code>. It will call a method 
     181named <code class="python">self.render_METHOD</code> 
     182where <q>METHOD</q> is whatever HTTP method was used to request this 
     183resource. Examples: request_GET, request_POST, request_HEAD, and so 
     184on. It is recommended that you have your resource classes 
     185subclass <code class="API" base="twisted.web.resource">Resource</code> 
     186and implement <code class="python">render_METHOD</code> methods as 
     187opposed to <code class="python">render</code> itself. Note that for 
     188certain resources, <code class="python">request_POST = 
     189request_GET</code> may be desirable in case one wants to process 
     190arguments passed to the resource regardless of whether they used GET 
    188191(<code>?foo=bar&amp;baz=quux</code>, and so forth) or POST. 
    189192 
    190193</p> 
    resource regardless of whether they used GET 
    201204<h2>Advanced Configuration</h2> 
    202205 
    203206<p>Non-trivial configurations of Twisted Web are achieved with Python 
    204 configuration files. This is a Python snippet which builds up a variable 
    205 called application. Usually, a <code class="API">twisted.application.internet.TCPServer</code> instance will 
    206 be used to make the application listen on a TCP port (80, in case direct 
    207 web serving is desired), with the listener being a 
    208 <code class="API">twisted.web.server.Site</code>. The resulting file can then 
    209 be run with <code class="shell">twistd -y</code>. Alternatively a reactor 
    210 object can be used directly to make a runnable script.</p> 
     207configuration files. This is a Python snippet which builds up a 
     208variable called application. Usually, 
     209a <code class="API">twisted.application.internet.TCPServer</code> 
     210instance will be used to make the application listen on a TCP port 
     211(80, in case direct web serving is desired), with the listener being 
     212a <code class="API">twisted.web.server.Site</code>. The resulting file 
     213can then be run with <code class="shell">twistd 
     214-y</code>. Alternatively a reactor object can be used directly to make 
     215a runnable script.</p> 
    211216 
    212217<p>The <code>Site</code> will wrap a <code>Resource</code> object -- the 
    213218root.</p> 
    reactor.run() 
    259264 
    260265<h3>Modifying File Resources</h3> 
    261266 
    262 <p><code>File</code> resources, be they root object or children thereof, 
    263 have two important attributes that often need to be modified: 
    264 <code>indexNames</code> and <code>processors</code>. <code>indexNames</code> 
    265 determines which files are treated as <q>index files</q> -- served 
    266 up when a directory is rendered. <code>processors</code> determine how 
    267 certain file extensions are treated.</p> 
     267<p><code>File</code> resources, be they root object or children 
     268thereof, have two important attributes that often need to be 
     269modified: <code>indexNames</code> 
     270and <code>processors</code>. <code>indexNames</code> determines which 
     271files are treated as <q>index files</q> -- served up when a directory 
     272is rendered. <code>processors</code> determine how certain file 
     273extensions are treated.</p> 
    268274 
    269275<p>Here is an example for both, creating a site where all <code>.rpy</code> 
    270276extensions are Resource Scripts, and which renders directories by 
    exists.</p> 
    308314 
    309315<h3>Virtual Hosts</h3> 
    310316 
    311 <p>Virtual hosting is done via a special resource, that should be 
    312 used as the root resource -- <code>NameVirtualHost</code>. 
    313 <code>NameVirtualHost</code> has an attribute named <code>default</code>, 
    314 which holds the default website. If a different root for some other 
    315 name is desired, the <code>addHost</code> method should be called.</p> 
     317<p>Virtual hosting is done via a special resource, that should be used 
     318as the root resource 
     319-- <code>NameVirtualHost</code>. <code>NameVirtualHost</code> has an 
     320attribute named <code>default</code>, which holds the default 
     321website. If a different root for some other name is desired, 
     322the <code>addHost</code> method should be called.</p> 
    316323 
    317324<pre class="python"> 
    318325from twisted.application import internet, service 
    it when it is not. 
    529536 
    530537<h3>Serving PHP/Perl/CGI</h3> 
    531538 
    532 <p>Everything related to CGI is located in the 
    533 <code>twisted.web.twcgi</code>, and it's here you'll find the classes that you 
    534 need to subclass in order to support the language of your (or somebody elses) 
    535 taste. You'll also need to create your own kind of resource if you are using a 
    536 non-unix operating system (such as Windows), or if the default resources has 
    537 wrong pathnames to the parsers.</p> 
     539<p>Everything related to CGI is located in 
     540the <code>twisted.web.twcgi</code>, and it's here you'll find the 
     541classes that you need to subclass in order to support the language of 
     542your (or somebody elses) taste. You'll also need to create your own 
     543kind of resource if you are using a non-unix operating system (such as 
     544Windows), or if the default resources has wrong pathnames to the 
     545parsers.</p> 
    538546 
    539547<p>The following snippet is a .rpy that serves perl-files. Look at <code>twisted.web.twcgi</code> 
    540548for more examples regarding twisted.web and CGI.</p> 
    from twisted.web import vhost 
    643651resource = vhost.VHostMonsterResource() 
    644652</pre> 
    645653 
    646 <p>Make sure the web server is configured with the correct processors for the 
    647 <code>rpy</code> extensions (the web server 
    648 <code>twistd web --path</code> generates by default is so configured).</p> 
     654<p>Make sure the web server is configured with the correct processors 
     655for the <code>rpy</code> extensions (the web server <code>twistd web 
     656--path</code> generates by default is so configured).</p> 
    649657 
    650658<p>From the Apache side, instead of using the following ProxyPass directive:</p> 
    651659 
    i.setServiceParent(sc) 
    684692 
    685693<h2>Rewriting URLs</h2> 
    686694 
    687 <p>Sometimes it is convenient to modify the content of the 
    688 <code class="API" base="twisted.web.server">Request</code> object 
     695<p>Sometimes it is convenient to modify the content of 
     696the <code class="API" base="twisted.web.server">Request</code> object 
    689697before passing it on. Because this is most often used to rewrite 
    690 either the URL, the similarity to Apache's <code>mod_rewrite</code> has 
    691 inspired the <code class="API">twisted.web.rewrite</code> module. Using 
    692 this module is done via wrapping a resource with a 
    693 <code class="API">twisted.web.rewrite.RewriterResource</code> which 
    694 then has rewrite rules. Rewrite rules are functions which accept a request 
    695 object, and possible modify it. After all rewrite rules run, the child 
    696 resolution chain continues as if the wrapped resource, rather than 
    697 the <code class="API" base="twisted.web.rewrite">RewriterResource</code>, 
    698 was the child.</p> 
     698either the URL, the similarity to Apache's <code>mod_rewrite</code> 
     699has inspired the <code class="API">twisted.web.rewrite</code> 
     700module. Using this module is done via wrapping a resource with 
     701a <code class="API">twisted.web.rewrite.RewriterResource</code> which 
     702then has rewrite rules. Rewrite rules are functions which accept a 
     703request object, and possible modify it. After all rewrite rules run, 
     704the child resolution chain continues as if the wrapped resource, 
     705rather than the <code class="API" 
     706base="twisted.web.rewrite">RewriterResource</code>, was the child.</p> 
    699707 
    700708<p>Here is an example, using the only rule currently supplied by Twisted 
    701709itself:</p> 
    itself:</p> 
    704712default_root = rewrite.RewriterResource(default, rewrite.tildeToUsers) 
    705713</pre> 
    706714 
    707 <p>This causes the URL <code>/~foo/bar.html</code> to be treated like 
    708 <code>/users/foo/bar.html</code>. If done after setting default's 
    709 <code>users</code> child to a 
    710 <code class="API" base="twisted.web">distrib.UserDirectory</code>, 
    711 it gives a configuration similar to the classical configuration of 
    712 web server, common since the first NCSA servers.</p> 
     715<p>This causes the URL <code>/~foo/bar.html</code> to be treated 
     716like <code>/users/foo/bar.html</code>. If done after setting 
     717default's <code>users</code> child to a <code class="API" 
     718base="twisted.web">distrib.UserDirectory</code>, it gives a 
     719configuration similar to the classical configuration of web server, 
     720common since the first NCSA servers.</p> 
    713721 
    714722<h2>Knowing When We're Not Wanted</h2> 
    715723 
    are frustrated after merely 10 seconds.</p> 
    741749 
    742750<h2>As-Is Serving</h2> 
    743751 
    744 <p>Sometimes, you want to be able to send headers and status directly. While 
    745 you can do this with a 
    746 <code base="twisted.web.script" class="API">ResourceScript</code>, an easier 
    747 way is to use <code base="twisted.web.static" class="API">ASISProcessor</code>. 
    748 Use it by, for example, adding it as a processor for the <code>.asis</code> 
    749 extension. Here is a sample file:</p> 
     752<p>Sometimes, you want to be able to send headers and status 
     753directly. While you can do this with a <code base="twisted.web.script" 
     754class="API">ResourceScript</code>, an easier way is to 
     755use <code base="twisted.web.static" class="API">ASISProcessor</code>. 
     756Use it by, for example, adding it as a processor for 
     757the <code>.asis</code> extension. Here is a sample file:</p> 
    750758 
    751759<pre> 
    752760HTTP/1.0 200 OK 
  • doc/web/howto/web-development.xhtml

    diff --git a/doc/web/howto/web-development.xhtml b/doc/web/howto/web-development.xhtml
    index 0a987d1..562cccf 100644
    a b all importing some Python module. This is a <em>bad idea</em> -- it mashes 
    8282deployment with development, and makes sure your users will be <em>tied</em> to 
    8383the file-system.</p> 
    8484 
    85 <p>We have <code>.rpy</code>s because they are useful and necessary.  But using 
    86 them incorrectly leads to horribly unmaintainable applications.  The best way to 
    87 ensure you are using them correctly is to not use them at all, until you are on 
    88 your <em>final</em> deployment stages.  You should then find your 
    89 <code>.rpy</code> files will be less than 10 lines, because you will not 
    90 <em>have</em> more than 10 lines to write.</p> 
     85<p>We have <code>.rpy</code>s because they are useful and necessary. 
     86But using them incorrectly leads to horribly unmaintainable 
     87applications.  The best way to ensure you are using them correctly is 
     88to not use them at all, until you are on your <em>final</em> 
     89deployment stages.  You should then find your <code>.rpy</code> files 
     90will be less than 10 lines, because you will not <em>have</em> more 
     91than 10 lines to write.</p> 
    9192 
    9293</body> 
    9394 
  • doc/web/howto/xmlrpc.xhtml

    diff --git a/doc/web/howto/xmlrpc.xhtml b/doc/web/howto/xmlrpc.xhtml
    index 38001e4..b0bb5cc 100644
    a b resource scripts. The following is an example of such a resource script:</p> 
    9999<h3>Using XML-RPC sub-handlers</h3> 
    100100 
    101101<p>XML-RPC resource can be nested so that one handler calls another if 
    102 a method with a given prefix is called. For example, to add support for 
    103 an XML-RPC method <code>date.time()</code> to the 
    104 <code class="python">Example</code> class, you could do the following:</p> 
     102a method with a given prefix is called. For example, to add support 
     103for an XML-RPC method <code>date.time()</code> to 
     104the <code class="python">Example</code> class, you could do the 
     105following:</p> 
    105106 
    106107<pre class="python"> 
    107108import time 
    using this method.</p> 
    142143 
    143144<h3>Adding XML-RPC Introspection support</h3> 
    144145 
    145 <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 
    146 methods in a <code>system</code> sub-handler which allow a client to query 
    147 a server about the server's API. Adding Introspection support to the 
    148 <code class="python">Example</code> class is easy using the 
    149 <code base="twisted.web.xmlrpc" class="API">XMLRPCIntrospection</code> 
    150 class:</p> 
     146<p>XML-RPC has an 
     147informal <a href="http://ldp.kernelnotes.de/HOWTO/XML-RPC-HOWTO/xmlrpc-howto-interfaces.html">Introspection 
     148API</a> that specifies three methods in a <code>system</code> 
     149sub-handler which allow a client to query a server about the server's 
     150API. Adding Introspection support to 
     151the <code class="python">Example</code> class is easy using 
     152the <code base="twisted.web.xmlrpc" 
     153class="API">XMLRPCIntrospection</code> class:</p> 
    151154 
    152155<pre class="python"> 
    153156from twisted.web import xmlrpc, server 
    if __name__ == '__main__': 
    181184    reactor.run() 
    182185</pre> 
    183186 
    184 <p>Note the method attributes <code class="python">help</code> and 
    185 <code class="python">signature</code> which are used by the Introspection 
    186 API methods <code>system.methodHelp</code> and 
    187 <code>system.methodSignature</code> respectively. If no 
    188 <code class="python">help</code> attribute is specified, 
    189 the method's documentation string is used instead.</p> 
     187<p>Note the method attributes <code class="python">help</code> 
     188and <code class="python">signature</code> which are used by the 
     189Introspection API methods <code>system.methodHelp</code> 
     190and <code>system.methodSignature</code> respectively. If 
     191no <code class="python">help</code> attribute is specified, the 
     192method's documentation string is used instead.</p> 
    190193 
    191194<h2>SOAP Support</h2> 
    192195 
    from the <code>xmlrpclib</code> way which should be noted:</p> 
    210213    <code>callRemote</code>.</li> 
    211214</ol> 
    212215 
    213 <p>The interface Twisted presents to XML-RPC client is that of a proxy object: 
    214 <code class="API">twisted.web.xmlrpc.Proxy</code>. The constructor for the 
    215 object receives a URL: it must be an HTTP or HTTPS URL. When an XML-RPC service 
    216 is described, the URL to that service will be given there.</p> 
     216<p>The interface Twisted presents to XML-RPC client is that of a proxy 
     217object: <code class="API">twisted.web.xmlrpc.Proxy</code>. The 
     218constructor for the object receives a URL: it must be an HTTP or HTTPS 
     219URL. When an XML-RPC service is described, the URL to that service 
     220will be given there.</p> 
    217221 
    218222<p>Having a proxy object, one can just call the <code>callRemote</code> method, 
    219223which accepts a method name and a variable argument list (but no named 
    def printError(error): 
    237241    print 'error', error 
    238242    reactor.stop() 
    239243 
    240 proxy = Proxy('http://advogato.org/XMLRPC') 
     244proxy = Proxy('http://advogato.oubunturg/XMLRPC') 
    241245proxy.callRemote('test.sumprod', 3, 5).addCallbacks(printValue, printError) 
    242246reactor.run() 
    243247</pre> 
    SOAP in the one web server, you can use the <code class="API" 
    257261base="twisted.web.resource.IResource">putChild</code> method of Resources.</p> 
    258262 
    259263<p>The following example uses an empty <code class="API" 
    260 base="twisted.web">resource.Resource</code> as the root resource for a <code 
    261 class="API" base="twisted.web.server">Site</code>, and then adds 
    262 <code>/RPC2</code> and <code>/SOAP</code> paths to it.</p> 
     264base="twisted.web">resource.Resource</code> as the root resource for 
     265a <code class="API" base="twisted.web.server">Site</code>, and then 
     266adds <code>/RPC2</code> and <code>/SOAP</code> paths to it.</p> 
    263267 
    264268<a href="listings/xmlAndSoapQuote.py" class="py-listing">xmlAndSoapQuote.py</a> 
    265269 
    266 <p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web 
     270<dh p>Refer to <a href="using-twistedweb.xhtml#development">Twisted Web 
    267271Development</a> for more details about Resources.</p> 
    268272 
    269273  </body>