Commits

Robert Brewer committed 6a11c71

1. Initial content for designchoices.xml.
2. Updates to gettingstarted.xml.

Comments (0)

Files changed (4)

docs/book/xml/appdeveloperreference.xml

          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" />
+    <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 you will use to build a CherryPy
+    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/designchoices.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="designchoices">
-  <title>Design choices</title>
-</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="designchoices">
+    <title>Design choices</title>
+    <section>
+        <title>A layered API</title>
+        <section>
+            <title>Simple apps should not require any knowledge of HTTP</title>
+            <para>At its most basic, CherryPy is designed to allow the production of simple websites
+            without having to think about any of the details of HTTP. Notice we're saying HTTP (the
+            transport), not HTML (the markup language)! In particular, developers should not have to
+            concern themselves with:</para>
+            <itemizedlist>
+                <listitem>
+                    <para>Responding to unpublished requests</para>
+                </listitem>
+                <listitem>
+                    <para>Logging and notifying users appropriately when unhandled exceptions
+                    occur</para>
+                </listitem>
+                <listitem>
+                    <para>The difference between query strings and POSTed params</para>
+                </listitem>
+                <listitem>
+                    <para>The decoding and unpacking of request headers and bodies, including file
+                    uploads</para>
+                </listitem>
+                <listitem>
+                    <para>Response status or headers</para>
+                </listitem>
+            </itemizedlist>
+            <para>For the most part, simple "page handlers" (functions attached to
+            <code>cherrypy.root</code>), should never have to refer to cherrypy at all! They receive
+            params via function arguments, and return content directly. Advanced functionality is
+            most often enabled via the built-in filters, which encapsulate the particulars of HTTP,
+            and can be completely controlled via the config file.</para>
+        </section>
+        <section>
+            <title>Advanced apps should have full control over (valid) HTTP output</title>
+            <para>Simple apps are produced simply, but when a developer needs to step out of the
+            mundane and provide real value, they should be able to leverage the complete power and
+            flexibility of the HTTP specification. In general, the HTTP request and response messages
+            are completely represented in the <code>cherrypy.request</code> and
+            <code>.response</code> objects. At the lowest level, a developer should be able to
+            generate any valid HTTP response message by modifying
+            <code>cherrypy.response.status</code>, <code>.headerMap</code>, and/or
+            <code>.body</code>.</para>
+        </section>
+    </section>
+</section>

docs/book/xml/fileuploadbehavior.xml

          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>
+    <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 method. 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/gettingstarted.xml

-<?xml version="1.0" encoding="utf-8"?>
-<chapter 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="gettingstarted">
-  <title>Getting started</title>
-  <section>
-    <abstract>
-      <para></para>
-    </abstract>
-    <title>Getting CherryPy</title>
-    <itemizedlist>
-      <listitem>From a release package</listitem>
-      <listitem>From the CherryPy subversion repository</listitem>
-    </itemizedlist>
-      
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter 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="gettingstarted">
+    <title>Getting started</title>
     <section>
-      <title>Release package</title>
-      <para>A release package is an official stable release of CherryPy. 
-      It means that the main features and issues that were decide to be 
-      integrated and fixed for a particular milestone have been.</para>
-      <para>The latest package is available from 
-      <ulink url="http://sourceforge.net/project/showfiles.php?group_id=56099">
-	the sourceforge repository</ulink> of the CherryPy project.
-	You need to pick up the latest version of the package.
-      </para>
+        <abstract>
+            <para>Since CherryPy is pure Python and has no dependencies, obtaining and installing it
+            is a snap.</para>
+        </abstract>
+        <title>Getting CherryPy</title>
+        <itemizedlist>
+            <listitem>From a release package</listitem>
+            <listitem>From the CherryPy subversion repository</listitem>
+        </itemizedlist>
+        <section>
+            <title>Release package</title>
+            <para>A "release package" is an official stable release of CherryPy. It means that the
+            main features and issues that were decided to be integrated and fixed for a particular
+            milestone, have been.</para>
+            <para>The latest package is available from <ulink
+            url="http://sourceforge.net/project/showfiles.php?group_id=56099">the sourceforge
+            repository</ulink> of the CherryPy project. You need to pick up the latest version of the
+            package.</para>
+        </section>
+        <section>
+            <title>Subversion repository</title>
+            <para>The CherryPy project uses Subversion to control access to its source code. Getting
+            CherryPy from the latest changeset is sometimes required because a bugfix or a feature is
+            only available from it. Keep in mind that subversion code is subject to change on a
+            regular basis; therefore, only use it if you know what you are doing.</para>
+            <para>To get the latest source code from the subversion repository, you first need to
+            install a SVN client. On Microsoft Windows, <ulink
+            url="http://tortoisesvn.tigris.org/">TortoiseSVN</ulink> is a good choice. Under Linux,
+            you can either use the <ulink url="http://subversion.tigris.org/">svn</ulink> command
+            line tools or use a graphical user interface such as <ulink
+            url="http://esvn.umputun.com/">eSVN</ulink>.</para>
+            <para>Once you have installed a svn client, you need to type the following command
+            :</para>
+            <cmdsynopsis>
+                <command>svn</command>
+                <arg choice="req">co</arg>
+                <arg choice="req">http://svn.cherrypy.org</arg>
+            </cmdsynopsis>
+            <para>This will download the complete source code to your computer.</para>
+        </section>
     </section>
     <section>
-      <title>Subversion repository</title>
-      <para>The CherryPy project uses subversion to control access to 
-      its source code. Getting CherryPy from the latest changeset is 
-      sometimes required because a bug or a feature is only available
-      from it. Keep in mind that subversion code is subject to change
-      on a regular basis, therefore only use it if you know what you 
-      do.</para>
-      <para>To get the latest source code from the subversion repository, 
-      you first need to install a SVN client. On Microsoft Windows, 
-      <ulink url="http://tortoisesvn.tigris.org/">TortoiseSVN</ulink>
-      is a good choice. Under Linux, you can either use the 
-      <ulink url="http://subversion.tigris.org/">svn</ulink> command 
-      line tools or use a graphical user interface such as 
-      <ulink url="http://esvn.umputun.com/">eSVN</ulink>.</para>
-      <para>Once you have installed a svn client, you need to type the
-      following command :</para>
-      <cmdsynopsis>
-	<command>svn</command>
-	<arg choice="req">co</arg>
-	<arg choice="req">http://svn.cherrypy.org</arg>
-      </cmdsynopsis>
-      <para>This will lead to having the complete source code downloaded
-      on to your computer.</para>
-    </section>
-  </section>
-  <section>
-    <title>Installing CherryPy</title>
-    <abstract>
-      <itemizedlist>
-	<listitem>From a release package</listitem>
-	<listitem>From the CherryPy subversion repository</listitem>
-      </itemizedlist>
-    </abstract>
-    <section>
-      <title>Release package</title>
-      <para>Installing CherryPy from a release package will take
-      three steps only. Type the following commands :
-      </para>
-      <cmdsynopsis>
-	<command>tar</command>
-	<arg choice="req">zxvf</arg>
-	<arg choice="req">CherryPy-2.0.0.tar.gz</arg>
-      </cmdsynopsis>
-      <para>Which will create the CherryPy-2.0.0 directory.</para>
-      <cmdsynopsis>
-	<command>cd</command>
-	<arg choice="req">CherryPy-2.0.0</arg>
-      </cmdsynopsis>
-      <para>Then if you are under Unix or Linux, you should be root
-      and issue the following command:</para>
-      <cmdsynopsis>
-	<command>python</command>
-	<arg choice="req">setup.py</arg>
-	<arg choice="req">install</arg>
-      </cmdsynopsis>
+        <title>Installing CherryPy</title>
+        <abstract>
+            <itemizedlist>
+                <listitem>From a release package</listitem>
+                <listitem>From the CherryPy subversion repository</listitem>
+            </itemizedlist>
+        </abstract>
+        <section>
+            <title>Release package</title>
+            <para>Installing CherryPy from a release package will take three steps only. Type the
+            following commands :</para>
+            <cmdsynopsis>
+                <command>tar</command>
+                <arg choice="req">zxvf</arg>
+                <arg choice="req">CherryPy-2.1.0.tar.gz</arg>
+            </cmdsynopsis>
+            <para>Which will create the CherryPy-2.1.0 directory.</para>
+            <cmdsynopsis>
+                <command>cd</command>
+                <arg choice="req">CherryPy-2.1.0</arg>
+            </cmdsynopsis>
+            <para>Then issue the following command (if you are under Unix or Linux, you should be
+            root):</para>
+            <cmdsynopsis>
+                <command>python</command>
+                <arg choice="req">setup.py</arg>
+                <arg choice="req">install</arg>
+            </cmdsynopsis>
+        </section>
+        <section>
+            <title>Subversion repository</title>
+            <para>If you have downloaded the source code from the CherryPy subversion repository,
+            then you should have a directory called svn.cherrypy.org. Then type the following
+            commands:</para>
+            <cmdsynopsis>
+                <command>cd</command>
+                <arg choice="req">svn.cherrypy.org/trunk</arg>
+            </cmdsynopsis>
+            <para>Then issue the following command (as root if you are under Unix/Linux):</para>
+            <cmdsynopsis>
+                <command>python</command>
+                <arg choice="req">setup.py</arg>
+                <arg choice="req">install</arg>
+            </cmdsynopsis>
+        </section>
     </section>
     <section>
-      <title>Subversion repository</title>
-      <para>If you have downloaded the source code from the CherryPy subversion
-      respository, then you should have a directory called svn.cherrypy.org.
-      Then type the following commands:</para>
-      <cmdsynopsis>
-	<command>cd</command>
-	<arg choice="req">svn.cherrypy.org/trunk</arg>
-      </cmdsynopsis>
-      <para>Then if you are under Unix or Linux, you should be root
-      and issue the following command (as root if you are under Unix/Linux:</para>
-      <cmdsynopsis>
-	<command>python</command>
-	<arg choice="req">setup.py</arg>
-	<arg choice="req">install</arg>
-      </cmdsynopsis>
+        <title>Running the test programs</title>
+        <para>If you have installed CherryPy from the source code downloaded from the subversion
+        repository, you can run the test suite to check if everything is fine on your system. Type
+        the following commands:</para>
+        <cmdsynopsis>
+            <command>cd</command>
+            <arg choice="req">svn.cherrypy.org/trunk/cherrypy/test</arg>
+        </cmdsynopsis>
+        <cmdsynopsis>
+            <command>python</command>
+            <arg choice="req">test.py</arg>
+        </cmdsynopsis>
+        <para>If all tests pass, then they will be flagged as <code>ok</code>. If an error occurs,
+        please visit the main CherryPy website to report the issue.</para>
     </section>
-  </section>
-  <section>
-    <title>Running the test programs</title>
-    <para>If you have installed CherryPy from the source code downloaded from
-    the subversion respository, you can run the test suite to check if everything 
-    is fine on your system. Type the following commands:</para>
-    <cmdsynopsis>
-      <command>cd</command>
-      <arg choice="req">svn.cherrypy.org/trunk/cherrypy/test</arg>
-    </cmdsynopsis>
-    <cmdsynopsis>
-      <command>python</command>
-      <arg choice="req">test.py</arg>
-    </cmdsynopsis>
-    <para>If all tests pass, then they will be flagged as <code>ok</code>. 
-    If an error occurs, please visit the main CherryPy website to report the issue.</para>
-  </section>
-</chapter>
+</chapter>
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.