Robert Brewer avatar Robert Brewer committed 483242a

doc proofing: appdeveloperreference

Comments (0)

Files changed (7)

docs/book/xml/appdeveloperreference.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="appdeveloperreference">
-    <title>Application developer reference</title>
-    <abstract>CherryPy tries to bring to Python developers a system that let them use their language
-        to develop web application as they would use it for any other type of environment. Therefore,
-        building a web application with CherryPy is very straightforward and does not require the
-        developer to change his/her habits, nor to learn many features before being able to pull out a
-        working application. This section will review the basic bricks offered by CherryPy to build an 
-        application.</abstract>
-    <xi:include href="globaloverviewcherrypy.xml"/>
-    <xi:include href="configsystemoverview.xml"/>
-    <xi:include href="sessions.xml"/>
-    <xi:include href="templateindependant.xml"/>
-    <xi:include href="staticcontenthandling.xml"/>
-    <xi:include href="fileuploadbehavior.xml"/>
-</section>
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="appdeveloperreference">
+  <title>Application developer reference</title>
+  <abstract>CherryPy lets developers use Python to develop web applications,
+  just as they would use Python for any other type of application. Building a
+  web application with CherryPy is very straightforward and does not require
+  the developer to change habits, or learn many features, before being able to
+  produce a working application. This section will review the basic components
+  which CherryPy provides to build an application.</abstract>
+  <xi:include href="globaloverviewcherrypy.xml" />
+  <xi:include href="configsystemoverview.xml" />
+  <xi:include href="sessions.xml" />
+  <xi:include href="templateindependant.xml" />
+  <xi:include href="staticcontenthandling.xml" />
+  <xi:include href="fileuploadbehavior.xml" />
+</section>

docs/book/xml/configsystemoverview.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="configsystemoverview">
-    <title>Configuration system overview</title>
-    <para>The CherryPy configuration system specifies with a fine grain how each part of the
-        application should react. You will use it for two reason: </para>
-    <itemizedlist>
-        <listitem>Web server settings</listitem>
-        <listitem>Enabling filters per path</listitem>
-    </itemizedlist>
-    <para>You will be able to declare the configuration settings either from a file or from a Python
-        dictionnary.</para>
-    <para>First of all, let&apos;s see how a typical configuration file is defined.</para>
-    <example>
-        <title>Configuration file</title>
-        <programlisting linenumbering="numbered">
-            #The configuration file called myconfigfile.conf
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="configsystemoverview">
+  <title>Configuration system overview</title>
+  <para>The CherryPy configuration system provides fine-grained control over
+  how each part of the application should react. You will use it for two
+  reasons:</para>
+  <itemizedlist>
+    <listitem>Web server settings</listitem>
+    <listitem>Enabling filters per path</listitem>
+  </itemizedlist>
+  <para>You will be able to declare the configuration settings either from a
+  file or from a Python dictionary.</para>
+  <para>First of all, let's see how a typical configuration file is
+  defined.</para>
+  <example>
+    <title>Configuration file</title>
+    <programlisting linenumbering="numbered">
+            # The configuration file called myconfigfile.conf
             [global]
             server.socketPort=8080
             server.socketHost=""
             # From your script...
             cherrypy.config.update(file="myconfigfile.conf") 
         </programlisting>
-    </example>
-    <para>The settings can also be defined using a python dictionnary instead of a file as follow :</para>
-    <example>
-        <title>Configuration dictionnary</title>
-        <programlisting linenumbering="numbered">
+  </example>
+  <para>The settings can also be defined using a python dictionary instead of
+  a file as follows:</para>
+  <example>
+    <title>Configuration dictionary</title>
+    <programlisting linenumbering="numbered">
       settings = { 
-         &apos;global&apos;: {
-            &apos;server.socketPort&apos; : 8080,
-            &apos;server.socketHost&apos;: "",
-            &apos;server.socketFile&apos;: "",
-            &apos;server.socketQueueSize&apos;: 5,
-            &apos;server.protocolVersion&apos;: "HTTP/1.0",
-            &apos;server.logToScreen&apos;: True,
-            &apos;server.logFile&apos;: "",
-            &apos;server.reverseDNS&apos;: False,
-            &apos;server.threadPool&apos;: 10,
-            &apos;server.environment&apos;: "development"
+         'global': {
+            'server.socketPort' : 8080,
+            'server.socketHost': "",
+            'server.socketFile': "",
+            'server.socketQueueSize': 5,
+            'server.protocolVersion': "HTTP/1.0",
+            'server.logToScreen': True,
+            'server.logFile': "",
+            'server.reverseDNS': False,
+            'server.threadPool': 10,
+            'server.environment': "development"
          },
-         &apos;/service/xmlrpc&apos; : {
-            &apos;xmlRpcFilter.on&apos;: True
+         '/service/xmlrpc' : {
+            'xmlRpcFilter.on': True
          },
-         &apos;/admin&apos;: {
-            &apos;sessionAuthenticateFilter.on&apos; :True
+         '/admin': {
+            'sessionAuthenticateFilter.on' :True
          },
-         &apos;/css/default.css&apos;: {
-            &apos;staticFilter.on&apos;: True,
-            &apos;staticFilter.file&apos;: "data/css/default.css"
+         '/css/default.css': {
+            'staticFilter.on': True,
+            'staticFilter.file': "data/css/default.css"
          }
       }
       cherrypy.config.update(settings)
         </programlisting>
-    </example>
-    <para>Each section of the configuration is a path that can be mapped to a published object
-        of the tree handled by CherryPy. Therefore when the server receives a request to
-            <code>/css/default.css</code> the static filter will be called and the server will
-        actually return the physical file name <filename>data/css/default.css</filename>. </para>
-    <para>Since the path <code>/service/xmlrpc</code> has the XML-RPC filter enabled, all the
-        exposed methods of the object <code>cherrypy.root.service.xmlrpc</code> will be treated as
-        XML-RPC methods.</para>
-    <para>The root entry, defined as <code>global</code>, is also responsible for defining the
-        server settings such as the port, the protocol version to use by default, the number of
-        threads to start with the server, etc.</para>
-    <para>The configuration file requires that all the value are Python values. Strings must be
-        quoted, boolean are set to True or False, etc.</para>
-    <para>The <code>server.environment</code> entry controls how CherryPy should run. Three values
-        are legal :</para>
-    <itemizedlist>
-        <listitem>development <itemizedlist>
-                <listitem>logDebugInfoFilter is enabled by default</listitem>
-                <listitem> the default _cpOnError displays tracebacks in the browser if errors occur
-                    but still returns a "200" status code</listitem>
-                <listitem>autoreload is enabled by default</listitem>
-            </itemizedlist>
+  </example>
+  <para>Each section of the configuration refers to a URL path; each path is
+  mapped to a published object of the tree handled by CherryPy. Therefore when
+  the server receives a request for <code>/css/default.css</code>, the static
+  filter will be called and the server will actually return the physical file
+  name <filename>data/css/default.css</filename>.</para>
+  <para>Since the path <code>/service/xmlrpc</code> has the XML-RPC filter
+  enabled, all the exposed methods of the object
+  <code>cherrypy.root.service.xmlrpc</code> will be treated as XML-RPC
+  methods.</para>
+  <para>The root entry, defined as <code>global</code>, is also responsible
+  for defining the server settings such as the port, the protocol version to
+  use by default, the number of threads to start with the server, etc.</para>
+  <para>All values in the configuration file must be valid Python values.
+  Strings must be quoted, booleans must be True or False, etc.</para>
+  <para>The <code>server.environment</code> entry controls how CherryPy should
+  run. Three values are legal:</para>
+  <itemizedlist>
+    <listitem>development <itemizedlist>
+        <listitem>logDebugInfoFilter is enabled by default</listitem>
+        <listitem>the default _cpOnError displays tracebacks in the browser if
+        errors occur</listitem>
+        <listitem>autoreload is enabled by default</listitem>
+      </itemizedlist></listitem>
+    <listitem>production <itemizedlist>
+        <listitem>logDebugInfoFilter is disabled by default</listitem>
+        <listitem>
+          <para>tracebacks are logged, but are not displayed in the
+          browser</para>
         </listitem>
-        <listitem>production <itemizedlist>
-                <listitem>logDebugInfoFilter is disabled by default</listitem>
-                <listitem>the default _cpOnError returns "304" or "500" status codes if errors
-                occur</listitem>
-            </itemizedlist>
-        </listitem>
-        <listitem>staging (same as production for the moment)</listitem>
-    </itemizedlist>
-</section>
+        <listitem>autoreload is disabled by default</listitem>
+      </itemizedlist></listitem>
+    <listitem>staging (same as production for the moment)</listitem>
+  </itemizedlist>
+</section>

docs/book/xml/fileuploadbehavior.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="globaloverviewcherrypy">
-    <title>File upload</title>
-    <para>Before version 2.1, CherryPy was handling file uploads as follows: it was reading the entire file in memory, store it in a string and pass it to the method. 
-        This works well for small files but not so well for big files.</para>
-        
-        <para>CherryPy 2.1 uses the python <code>cgi</code> module to parse the POST data. 
-            When a file is being uploaded, this modules stores it in a temp file and returns a <code>FieldStorage</code> instance which contains information about this file. 
-            CherryPy then passes this <code>FieldStorage</code> instance to the method, this instance has the following attributes:</para>
-        
-    <itemizedlist>
-        <listitem><code>file</code>: the file(-like) object from which you can read the data</listitem>
-        <listitem><code>filename</code>: the client-side filename</listitem>
-        <listitem><code>type</code>: the content-type of the file </listitem>
-    </itemizedlist>
-    </section>
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="globaloverviewcherrypy">
+  <title>File upload</title>
+  <para>Before version 2.1, CherryPy handled file uploads by reading the
+  entire file into memory, storing it in a string, and passing it to the page
+  handler. This worked well for small files, but not so well for large
+  files.</para>
+  <para>CherryPy 2.1 uses the python <code>cgi</code> module to parse the POST
+  data. When a file is being uploaded, the <code>cgi</code> module stores it
+  in a temp file and returns a <code>FieldStorage</code> instance which
+  contains information about this file. CherryPy then passes this
+  <code>FieldStorage</code> instance to the method. The
+  <code>FieldStorage</code> instance has the following attributes:</para>
+  <itemizedlist>
+    <listitem><code>file</code>: the file(-like) object from which you can
+    read the data</listitem>
+    <listitem><code>filename</code>: the client-side filename</listitem>
+    <listitem><code>type</code>: the content-type of the file</listitem>
+  </itemizedlist>
+</section>

docs/book/xml/globaloverviewcherrypy.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="globaloverviewcherrypy">
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="globaloverviewcherrypy">
   <title>Filters</title>
-  <para>Filters are one of the most important features of CherryPy. A filter is a class defining a
-    set of function that will be called by the core at specific point of a request processing. The
-    very nature of filters are to let the developer write code that will be called at a low level -
-    the HTTP request/response level - and therefore should only be used in that context.</para>
-  <para>CherryPy comes with a set of filters which are turned off by default. To enable them, you
-    must use the configuration system as follow :</para>
+  <para>Filters are one of the most important features of CherryPy. The
+  CherryPy core can call user-defined functions at specific points during
+  request processing; a filter is a class which defines those functions.
+  Filters are designed to be called at a low level—the HTTP request/response
+  level—and therefore should only be used in that context.</para>
+  <para>CherryPy comes with a set of built-in filters, but they're turned off
+  by default. To enable them, you must use the configuration system as
+  follows:</para>
   <itemizedlist>
-    <listitem>First you must decide at which level of the cherrypy tree of published objects you
-      need the filter to act on. The filter will then act on that level and all its sub-levels in
-      the tree. Remember that the tree is accessed as a path and then mapped internally by the core
-      to match the correct exposed object.</listitem>
-    <listitem>Second in the config file you must turn the filter on like this : <code>filterName.on
-        = True</code></listitem>
+    <listitem>First you must decide where to enable the filter. CherryPy
+    maintains a tree of published objects; you must decide which branch should
+    use the filter. The filter will then apply to that branch and all its
+    children in the tree. Remember that the tree is accessed as a path and
+    then mapped internally by the core to match the correct exposed
+    object.</listitem>
+    <listitem>Second in the config file you must turn the filter on like this
+    : <code>filterName.on = True</code></listitem>
   </itemizedlist>
   <example>
     <title>Turning on a default filter</title>
         tidyFilter.strictXml = True
       </programlisting>
   </example>
-  <para> On the first line we define that when the path <code>/entries/view</code> is called, or one
-    of its sub-paths, the tidy filter will be used by the core. On the two last lines we also define
-    some parameters used by the filter. </para>
-  <para>CherryPy lets you write your own filters as we will see in the developer reference chapter.
-    Nonetheless the way to use them is different from the default filters since you do not declare
-    them within the configuration file but from the source code itself using the
-    <code>_cpFilterList</code> list as a class member of the object that will use the filter.</para>
+  <para>On the first line we define that the tidy filter will be used by the
+  core whenever the path <code>/entries/view</code> (or one of its sub-paths)
+  is called. On the two last lines we also define some parameters used by the
+  filter.</para>
+  <para>CherryPy lets you write your own filters as we will see in the
+  developer reference chapter. However, the way to use them is different from
+  the default filters. You do not declare custom filters within the
+  configuration file; instead, use the <code>_cpFilterList</code> attribute in
+  your source code:</para>
   <example>
     <title>Using a non default filter</title>
     <programlisting linenumbering="numbered">
         cherrypy.server.start()
       </programlisting>
   </example>
-  <para>As all objects below <code>cherrypy.root.entries</code> will inherit the filter, there is no
-    need to re-specify it in each <code>_cpFilterList</code> underneath.</para>
-  <para>Keep in mind that the user defined filters are called in the order you add them to the
-  list.</para>
-</section>
+  <para>As all objects below <code>cherrypy.root.entries</code> will inherit
+  the filter, there is no need to re-specify it in each
+  <code>_cpFilterList</code> underneath.</para>
+  <para>Keep in mind that the user-defined filters are called in the order you
+  add them to the list.</para>
+</section>

docs/book/xml/sessions.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="sessions">
-    <title>Session Management</title>
-    <abstract>
-        <para>CherryPy 2.1 includes a powerful sessions system provided via a new <literal>sessionFilter</literal>. </para>
-    </abstract>
-    <section id="usingsessions">
-        <title>Using Sessions</title>
-        <para>First you need to enable the session filter through the configuration system, by setting <option>sessionFilter.on</option> to <literal>True</literal>. This gives you a variable called <literal>cherrypy.session</literal>, which is a dictionary-like object where you can read/store your session data. This dictionnary always has a special key called <literal>_id</literal> which contains the session id.</para>
-        <para>Here is a sample code showing how to implement a simple counter using sessions:</para>
-        <example>
-            <programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="sessions">
+  <title>Session Management</title>
+  <abstract>
+    <para>CherryPy 2.1 includes a powerful sessions system provided via a new
+    <literal>sessionFilter</literal>.</para>
+  </abstract>
+  <section id="usingsessions">
+    <title>Using Sessions</title>
+    <para>First you need to enable the session filter through the
+    configuration system, by setting <option>sessionFilter.on</option> to
+    <literal>True</literal>. This gives you a variable called
+    <literal>cherrypy.session</literal>, which is a dictionary-like object
+    where you can read/store your session data. This dictionary always has a
+    special key called <literal>_id</literal> which contains the session
+    id.</para>
+    <para>Here is sample code showing how to implement a simple counter using
+    sessions:</para>
+    <example>
+      <programlisting>
             import cherrypy
             class Root:
                 def index(self):
             cherrypy.config.update({'sessionFilter.on': True})
             cherrypy.server.start()
             </programlisting>
-        </example>
-    </section>
-    <section>
-        <title>Configuring sessions</title>
-        <para> The following configuration options are available for "sessionFilter": </para>
-        <itemizedlist>
-            <listitem>
-                <para><option>sessionFilter.on</option>:
-                <literal>True</literal> or <literal>False</literal> (default): enable/disable sessions</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.storageType</option>:
-                Specify which storage type should be used for storing session data on the server. Built-in types are <literal>Ram</literal> (default), <literal>File</literal> and <literal>PostgreSQL</literal> (see <xref linkend="backends"/> for more info)</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.timeout</option>:
-                The number of minutes of inactivity before an individual session can be removed. It can be a float (ex: 0.5 for 30 seconds). Defaults to 60.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.cleanUpDelay</option>:
-                Once in a while the server cleans up old/expired sessions. This config option specifies how often this clean up process should happe. The delay is in minutes. Defaults to 5.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.cookieName</option>:
-                The name of the cookie that CherryPy will use to store the session ID. Defaults to <literal>sessionID</literal>.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.getDB</option>:
-                See the <option>PostgreSQL</option> backend from <xref linkend="backends"/>.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.deadlockTimeout</option>:
-                See <xref linkend="concurrent"/>.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.onCreateSession</option>:
-                See <xref linkend="callbacks"/>.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.onDeleteSession</option>:
-                See <xref linkend="callbacks"/>.</para>
-            </listitem>
-            <listitem>
-                <para><option>sessionFilter.storageClass</option>:
-                See <xref linkend="custombackend"/>.</para>
-            </listitem>
-        </itemizedlist>
-    </section>
-
-    <section id="backends">
-        <title>Choosing the backend</title>
-        <para>CherryPy comes with multiple build-in backends for storing session data on the server side. They are:</para>
-
-        <itemizedlist>
-            <listitem>
-                <para><option>Ram</option>:
-                All data is stored in RAM; this is the fastest storage, but it means that the data will be lost if you restart the server; and it also means that it won't scale to multiple processes/machines</para>
-            </listitem>
-            <listitem>
-                <para><option>File</option>:
-                All data is stored on disk; this is a bit slower than Ram storage, but the data will persist if you restart the server server; it also means that data can also be shared amongst multiple CherryPy processes (either on the same machine, or on multiple machines if all machines have access to the same disk ... through something like NFS for instance)</para>
-            </listitem>
-            <listitem>
-                <para><option>PostgreSQL</option>:
-                This backend is included with CherryPy to show how easy it is to implement your own custom backend for the session system. All data is stored in a PostgreSQL database; storing your data in a database is the recommend setup for production if you have a very high traffic website and you need to scale your site accross multiple machines. To use this backend you'll need to create the following table in your PostgreSQL database:
-                <screen>
+    </example>
+  </section>
+  <section>
+    <title>Configuring sessions</title>
+    <para>The following configuration options are available for
+    "sessionFilter":</para>
+    <itemizedlist>
+      <listitem>
+        <para><option>sessionFilter.on</option>: <literal>True</literal> or
+        <literal>False</literal> (default): enable/disable sessions</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.storageType</option>: Specify which
+        storage type should be used for storing session data on the server.
+        Built-in types are <literal>Ram</literal> (default),
+        <literal>File</literal> and <literal>PostgreSQL</literal> (see <xref
+        linkend="backends" /> for more info)</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.timeout</option>: The number of minutes of
+        inactivity before an individual session can be removed. It can be a
+        float (ex: 0.5 for 30 seconds). Defaults to 60.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.cleanUpDelay</option>: Once in a while the
+        server cleans up old/expired sessions. This config option specifies
+        how often this clean up process should happen. The delay is in
+        minutes. Defaults to 5.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.cookieName</option>: The name of the
+        cookie that CherryPy will use to store the session ID. Defaults to
+        <literal>sessionID</literal>.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.getDB</option>: See the
+        <option>PostgreSQL</option> backend from <xref
+        linkend="backends" />.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.deadlockTimeout</option>: See <xref
+        linkend="concurrent" />.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.onCreateSession</option>: See <xref
+        linkend="callbacks" />.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.onDeleteSession</option>: See <xref
+        linkend="callbacks" />.</para>
+      </listitem>
+      <listitem>
+        <para><option>sessionFilter.storageClass</option>: See <xref
+        linkend="custombackend" />.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+  <section id="backends">
+    <title>Choosing the backend</title>
+    <para>CherryPy comes with multiple build-in backends for storing session
+    data on the server side. They are:</para>
+    <itemizedlist>
+      <listitem>
+        <para><option>Ram</option>: All data is stored in RAM; this is the
+        fastest storage, but it means that the data will be lost if you
+        restart the server; and it also means that it won't scale to multiple
+        processes/machines</para>
+      </listitem>
+      <listitem>
+        <para><option>File</option>: All data is stored on disk; this is a bit
+        slower than Ram storage, but the data will persist if you restart the
+        server. It also means that data can be shared amongst multiple
+        CherryPy processes, either on the same machine, or on multiple
+        machines if all machines have access to the same disk (for example,
+        via NFS).</para>
+      </listitem>
+      <listitem><para><option>PostgreSQL</option>: This backend is included
+      with CherryPy to show how easy it is to implement your own custom
+      backend for the session system. All data is stored in a PostgreSQL
+      database; storing your data in a database is the recommend setup for
+      production if you have a very high traffic website and you need to scale
+      your site across multiple machines. To use this backend, you'll need to
+      create the following table in your PostgreSQL database: <screen>
                 create table session (
                     id varchar(40),
                     data text,
                     expiration_time timestamp
                 )
-                </screen>
-                </para>
-                You also need to programmatically set the <literal>sessionFilter.getDB</literal> config option to a function that returns a DB connection.
-            </listitem>
-        </itemizedlist>
-    </section>
-
-    <section id="custombackend">
-        <title>Writing your own custom backend</title>
-        <para>By default, CherryPy comes with 3 built-in backends, but if you have specific needs, it is very easy to implement your own custom backend (for instance, another database, or an XML-RPC server, ...). To do so, all you have to do is write a class that implements the following methods:
-            <screen>
+                </screen> </para> You also need to programmatically set the
+      <literal>sessionFilter.getDB</literal> config option to a function that
+      returns a DB connection.</listitem>
+    </itemizedlist>
+  </section>
+  <section id="custombackend">
+    <title>Writing your own custom backend</title>
+    <para>By default, CherryPy comes with 3 built-in backends, but if you have
+    specific needs, it is very easy to implement your own custom backend (for
+    instance, another database, or an XML-RPC server, ...). To do so, all you
+    have to do is write a class that implements the following methods:
+    <screen>
             class MyCustomBackend:
                 def save(self, id, data, expirationTime):
                     """ Save the session data and expirationTime for that session id """
                 def cleanUp(self):
                     """ Delete expired session data from storage and call
                         'onDeleteSession' for each deleted session id """
-            </screen>
-            Note that if you want to use <option>explicit</option> locking (see <xref linkend="concurrent"/>), you also have to implement two extra methods: <literal>acquireLock</literal> and <literal>releaseLock</literal>.
-        </para>
-
-        <para>Once you have written this class, you have to programmatically set the <literal>sessionFilter.storageClass</literal> config option to this class.</para>
-
-        <para>If you need help in writing your own custom backend it is a good idea to look at how the current ones (ram, file and postgresql) are implemented. They are implemented in the file <filename>cherrypy/lib/filter/sessionfilter.py</filename></para>
-    </section>
-
-    <section id="concurrent">
-        <title>Handling concurrent requests for the same session data</title>
-        <para>It is normally quite rare to have two simultaneous requests with the same session ID. It means that a same browser is making 2 requests to your server at the same time (to dynamic pages ... static data like images don't have sessions). However, this case can happen (if you're using frames for instance), and it will happen more and more often as more and more people start using Ajax.</para>
-        <para>In that case, we need to make sure that access to the session data is serialized. This way threads can't both modify the data at the same time and leave it in an inconsistent state.</para>
-        <para>By default, CherryPy will serialize access to the session data, so if a browser makes a second request while a first request is still being handled by the server, the second request will block while the first request is accessing the data. As soon as the first request is finished then the second request will be able to access it.</para>
-        <para>This means that the second request will block until the first request is finished. If you're using the <option>ram</option> backend, you can manually shorten the window where the second request will block. This is achieved by having the first request explicitely tell CherryPy when it starts using the session data and when it is finished with it. In order to do so, you have to call <literal>cherrypy.session.acquireLock</literal> and <literal>cherrypy.session.releaseLock</literal>. You also have to set the <literal>sessionFilter.locking</literal> config option to <option>explicit</option>.</para>
-        <para>Note that this technique only works with the <option>ram</option> backend. For other backends like <option>file</option> or <option>postgresql</option>, it is not safe to release the session before the request is finished, because the session data will only be saved at the end of the request anyway. So it would be bad if some other thread started accessing the data between the time when it is released and the time when it is saved.
-        </para>
-    </section>
-
-    <section id="callbacks">
-        <title>Being notified when sessions are created/deleted</title>
-        <para>It is possible to configure the <literal>sessionFilter</literal> so that it calls some special callback functions from your code when sessions are being created/deleted. To do so you have to set the <literal>sessionFilter.onCreateSession</literal> and <literal>sessionFilter.onDeleteSession</literal> config options. When a session is created/deleted, CherryPy will call these functions and pass them the session data.</para>
-    </section>
-</section>
-
+            </screen> Note that if you want to use <option>explicit</option>
+    locking (see <xref linkend="concurrent" />), you also have to implement
+    two extra methods: <literal>acquireLock</literal> and
+    <literal>releaseLock</literal>.</para>
+    <para>Once you have written this class, you have to programmatically set
+    the <literal>sessionFilter.storageClass</literal> config option to this
+    class.</para>
+    <para>If you need help in writing your own custom backend it is a good
+    idea to look at how the current ones (ram, file and postgresql) are
+    implemented. They are implemented in the file
+    <filename>cherrypy/lib/filter/sessionfilter.py</filename></para>
+  </section>
+  <section id="concurrent">
+    <title>Handling concurrent requests for the same session data</title>
+    <para>It is normally quite rare to have two simultaneous requests with the
+    same session ID. It means that a same browser is making 2 requests to your
+    server at the same time (to dynamic pages ... static data like images
+    don't have sessions). However, this case can happen (if you're using
+    frames for instance), and it will happen more and more often as more and
+    more people start using Ajax.</para>
+    <para>In that case, we need to make sure that access to the session data
+    is serialized. This way, threads can't both modify the data at the same
+    time and leave it in an inconsistent state.</para>
+    <para>By default, CherryPy will serialize access to the session data, so
+    if a browser makes a second request while a first request is still being
+    handled by the server, the second request will block while the first
+    request is accessing the data. As soon as the first request is finished
+    then the second request will be able to access it.</para>
+    <para>This means that the second request will block until the first
+    request is finished. If you're using the <option>ram</option> backend, you
+    can manually shorten the window where the second request will block. This
+    is achieved by having the first request explicitly tell CherryPy when it
+    starts using the session data and when it is finished with it. In order to
+    do so, you have to call <literal>cherrypy.session.acquireLock</literal>
+    and <literal>cherrypy.session.releaseLock</literal>. You also have to set
+    the <literal>sessionFilter.locking</literal> config option to
+    <option>explicit</option>.</para>
+    <para>Note that this technique only works with the <option>ram</option>
+    backend. For other backends like <option>file</option> or
+    <option>postgresql</option>, it is not safe to release the session before
+    the request is finished, because the session data will only be saved at
+    the end of the request anyway. So it would be bad if some other thread
+    started accessing the data between the time when it is released and the
+    time when it is saved.</para>
+  </section>
+  <section id="callbacks">
+    <title>Being notified when sessions are created/deleted</title>
+    <para>It is possible to configure the <literal>sessionFilter</literal> so
+    that it calls some special callback functions from your code when sessions
+    are being created/deleted. To do so you have to set the
+    <literal>sessionFilter.onCreateSession</literal> and
+    <literal>sessionFilter.onDeleteSession</literal> config options. When a
+    session is created/deleted, CherryPy will call these functions and pass
+    them the session data.</para>
+  </section>
+</section>

docs/book/xml/staticcontenthandling.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="globaloverviewcherrypy">
-    <title>Static content handling</title>
-    <para>Static content is now handled by a filter called "staticFilter" that can easily be enabled and configured in your config file. 
-        For instance, if you wanted to serve <code>/style.css</code> from <filename>/home/site/style.css</filename> and <code>/static/*</code>
-        from <filename>/home/site/static/*</filename>, you can use the following configuration:
-        </para>
-        
-    <example>
-        <title>Static filter configuration</title>
-        <programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="globaloverviewcherrypy">
+  <title>Static content handling</title>
+  <para>Static content is now handled by a filter called "staticFilter" that
+  can easily be enabled and configured in your config file. For instance, if
+  you wanted to serve <code>/style.css</code> from
+  <filename>/home/site/style.css</filename> and <code>/static/*</code> from
+  <filename>/home/site/static/*</filename>, you can use the following
+  configuration:</para>
+  <example>
+    <title>Static filter configuration</title>
+    <programlisting>
             [global]
             staticFilter.root = "/home/site"
             
             staticFilter.on = True
             staticFilter.dir = "static"
         </programlisting>
-    </example>
-    <para>The <code>staticFilter.root</code> entry is not required; if you omit it, it defaults to the directory of your <code>cherrypy.root</code> class. </para>
-   </section>
+  </example>
+  <para>The <code>staticFilter.root</code> entry can be either absolute or
+  relative. If absolute, static content is sought within that absolute path.
+  Since CherryPy cannot guess where your application root is located, relative
+  paths are assumed to be relative to the directory where your
+  <code>cherrypy.root</code> class is defined (if you do not provide a root,
+  it defaults to "", and therefore to the directory of your
+  <code>cherrypy.root</code> class).</para>
+  <para>As an application developer, the design of your application affects
+  whether you choose to use absolute or relative paths. If you are creating a
+  one-off application that will only be deployed once, you might as well use
+  absolute paths. But you can make multiple deployments easier by using
+  relative paths, letting CherryPy calculate the absolute path each time for
+  you. Absolute paths, however, give deployers the ability to place static
+  content on read-only filesystems, or on faster disks.</para>
+</section>

docs/book/xml/templateindependant.xml

-<?xml version="1.0" encoding="utf-8"?>
-<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
-    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="templateindependant">
-    <title>Templating language independant</title>
-    <para>CherryPy is a low level framework to build web application and thus does not 
-    offer high level features such as an integrated templating system. This is quite a different
-        point of view from the other web frameworks already existing.</para>
-    <para>The great point is that CherryPy does not force you to use a specific tamplating language,
-       instead it allows you to plug your favourite one the way you need.
-    </para>
-    <para>CherryPy has been reported to be working with all the main templating systems:</para>
-    <itemizedlist>
-        <listitem>
-            <ulink url="http://www.cheetahtemplate.org">Cheetah</ulink>
-        </listitem>
-        <listitem>
-            <ulink url="http://www.w3.org/TR/xslt">
-                XSLT
-            </ulink>
-            </listitem>
-        <listitem>
-            <ulink url="http://cherrytemplate.python-hosting.com/">
-                CherryTemplate
-            </ulink>
-        </listitem>
-        <listitem>
-            <ulink url="http://freespace.virgin.net/hamish.sanderson/htmltemplate.html">
-                HTMLTemplate
-            </ulink>
-        </listitem>
-        <listitem>
-            <ulink url="http://lesscode.org/projects/kid">
-                Kid
-            </ulink>
-        </listitem>
-        <listitem>
-            <ulink url="http://www.zope.org/DevHome/Wikis/DevSite/Projects/ZPT/FrontPage">
-                Zope Page Template
-            </ulink>
-        </listitem>
-    </itemizedlist>
-    <para>You will find recipes on how to use them on the CherryPy website.</para>
-</section>
+<?xml version="1.0" encoding="UTF-8"?>
+<section xmlns:db="http://docbook.org/docbook-ng"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+         xml:id="templateindependant">
+  <title>Templating language independent</title>
+  <para>CherryPy is a low-level framework for building web applications, and
+  thus does not offer high-level features such as an integrated templating
+  system. This is quite a different point of view from many other web
+  frameworks. CherryPy does not force you to use a specific templating
+  language; instead, it allows you to plug in your favourite one as you see
+  fit.</para>
+  <para>CherryPy works with all the main templating systems:</para>
+  <itemizedlist>
+    <listitem>
+      <ulink url="http://www.cheetahtemplate.org">Cheetah</ulink>
+    </listitem>
+    <listitem>
+      <ulink url="http://www.w3.org/TR/xslt">XSLT</ulink>
+    </listitem>
+    <listitem>
+      <ulink
+      url="http://cherrytemplate.python-hosting.com/">CherryTemplate</ulink>
+    </listitem>
+    <listitem>
+      <ulink
+      url="http://freespace.virgin.net/hamish.sanderson/htmltemplate.html">HTMLTemplate</ulink>
+    </listitem>
+    <listitem>
+      <ulink url="http://lesscode.org/projects/kid">Kid</ulink>
+    </listitem>
+    <listitem>
+      <ulink
+      url="http://www.zope.org/DevHome/Wikis/DevSite/Projects/ZPT/FrontPage">Zope
+      Page Template</ulink>
+    </listitem>
+  </itemizedlist>
+  <para>You will find recipes on how to use them on the <ulink
+  url="http://www.cherrypy.org">CherryPy website</ulink>.</para>
+</section>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.