use Response; fix text

3 files changed, 40 insertions, 66 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 70cf4cabf..3d66be648 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,11 +13,11 @@ Here is one of the simplest :app:`Pyramid` applications you can make.
 
 .. literalinclude:: narr/helloworld.py
 
-See :ref:`firstapp_chapter` for a full explanation of how this :ref:`helloworld_imperative`
-app works. Read the :ref:`narrative_documentation` to understand how :app:`Pyramid` is designed
-to scale from these simple beginnings to handle the largest of web application needs. If your
-familiar with other web frameworks you might want to look at :ref:`design_defense` to understand
-why :app:`Pyramid` has been designed the way it has.
+See :ref:`firstapp_chapter` for a full explanation of how this
+:ref:`helloworld_imperative` app works. Read the
+:ref:`narrative_documentation` to understand how :app:`Pyramid` is designed
+to scale from these simple beginnings to handle the largest of web
+application needs.
 
 Front Matter
 ============
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index 447348be3..55829bef0 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -20,7 +20,6 @@ Here's one of the very simplest :app:`Pyramid` applications:
 .. literalinclude:: helloworld.py
    :linenos:
 
-
 When this code is inserted into a Python script named ``helloworld.py`` and
 executed by a Python interpreter which has the :app:`Pyramid` software
 installed, an HTTP server is started on TCP port 8080:
@@ -30,8 +29,8 @@ installed, an HTTP server is started on TCP port 8080:
    $ python helloworld.py
    serving on 0.0.0.0:8080 view at http://127.0.0.1:8080
 
-When port 8080 is visited by a browser on the  URL (``/hello/world``), the server
-will simply serve up the text "Hello world!" 
+When port 8080 is visited by a browser on the URL ``/hello/world``, the
+server will simply serve up the text "Hello world!"
 
 Press ``Ctrl-C`` to stop the application.
 
@@ -46,7 +45,7 @@ statements:
 
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 1-2
+   :lines: 1-3
 
 The script imports the :class:`~pyramid.config.Configurator` class from the
 :mod:`pyramid.config` module.  An instance of the
@@ -59,6 +58,9 @@ protocol to connect an application and a web server together.  The
 convenience, as the ``paste`` package is a dependency of :app:`Pyramid`
 itself.
 
+The script also imports the :class:`pyramid.response.Response` class for
+later use.  An instance of this class will be used to create a web response.
+
 View Callable Declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -70,8 +72,10 @@ named ``hello_world``.
    :pyobject: hello_world
 
 This function doesn't do anything very difficult.  The functions accepts a
-single argument (``request``).  The ``hello_world`` function returns a value
-computed from arguments matched from the url route.
+single argument (``request``).  The ``hello_world`` function returns an
+instance of the :class:`pyramid.response.Response`.  The single argument to
+the class' constructor is value computed from arguments matched from the url
+route.  This value becomes the body of the response.
 
 This function is known as a :term:`view callable`.  A view callable
 accepts a single argument, ``request``.  It is expected to return a
@@ -85,16 +89,11 @@ active :term:`WSGI` server.
 
 A view callable is required to return a :term:`response` object because a
 response object has all the information necessary to formulate an actual HTTP
-response; this object is then converted to text by the upstream :term:`WSGI`
-server and sent back to the requesting browser.  To return a response, each
-view callable creates an instance of the :class:`~pyramid.response.Response`
-class.  In the ``hello_world`` function, the string is passed.
-
-.. note:: As we'll see in later chapters, returning a literal
-   :term:`response` object from a view callable is not always required; we
-   can instead use a :term:`renderer` in our view configurations.  If we use
-   a renderer, our view callable is allowed to return a value that the
-   renderer understands, and the renderer generates a response on our behalf.
+response; this object is then converted to text by the :term:`WSGI` server
+which called Pyramid and it is sent back to the requesting browser.  To
+return a response, each view callable creates an instance of the
+:class:`~pyramid.response.Response` class.  In the ``hello_world`` function,
+a string is passed as the body to the response.
 
 .. index::
    single: imperative configuration
@@ -113,7 +112,7 @@ defined imports and function definitions, placed within the confines of an
 
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 7-12
+   :lines: 8-13
 
 Let's break this down piece-by-piece.
 
@@ -122,7 +121,7 @@ Configurator Construction
 
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 7-8
+   :lines: 8-9
 
 The ``if __name__ == '__main__':`` line in the code sample above represents a
 Python idiom: the code inside this if clause is not invoked unless the script
@@ -155,41 +154,15 @@ Adding Configuration
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 9-10
-
-First line is to call the :meth:`pyramid.config.Configurator.add_route`
-which registers a :term:`route` to match any url with ``/hello/`` followed
-by a string. The :meth:`pyramid.config.Configurator.add_view` method of
-a configurator registers a :term:`view configuration` within the
-:term:`application registry`.  A :term:`view configuration` and
-:term:`route configuration` represents a set of circumstances related to the
-:term:`request` that will cause a specific :term:`view callable` to be
-invoked.  This "set of circumstances" is provided as one or more keyword
-arguments to the ``add_view`` method.  Each of these keyword arguments is
-known as a view configuration :term:`predicate`.
-
-The line ``config.add_view(hello_world, route_name='hello')`` registers the
-``hello_world`` function as a view callable.  The ``add_view`` method
-of a Configurator must be called with a view callable object or a
-:term:`dotted Python name` as its
-first argument, so the first argument passed is the ``hello_world`` function.
-This line calls ``add_view`` with a ``route_name`` ``predicate`` value of
-``hello``.  This means that we're instructing
-:app:`Pyramid` to invoke the ``hello_world`` view callable if the
-:term:`route` is matched is ``hello``.  In :app:`Pyramid` the use of a
-:term:`route` is only one of ways you can link a url to a :term:`view callable`
-and is called :term:`URL Dispatch`.
-
-Each invocation of the ``add_view`` method registers a :term:`view
-configuration`.  Each :term:`predicate` provided as a keyword argument to the
-``add_view`` method narrows the set of circumstances which would cause the
-view configuration's callable to be invoked.  In general, a greater number of
-predicates supplied along with a view configuration will more strictly limit
-the applicability of its associated view callable.  When :app:`Pyramid`
-processes a request, the view callable with the *most specific* view
-configuration (the view configuration that matches the most specific set of
-predicates) is always invoked. In this application, :app:`Pyramid` chooses the most specific view callable
-based only on view :term:`predicate` applicability.
+   :lines: 10-11
+
+First line above calls the :meth:`pyramid.config.Configurator.add_route`
+method, which registers a :term:`route` to match any url path that begins
+with ``/hello/`` followed by a string.
+
+The second line, ``config.add_view(hello_world, route_name='hello')``,
+registers the ``hello_world`` function as a :term:`view callable` and makes
+sure that it will be called when the ``hello`` route is matched.
 
 .. index::
    single: make_wsgi_app
@@ -201,7 +174,7 @@ WSGI Application Creation
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 11
+   :lines: 12
 
 After configuring views and ending configuration, the script creates a WSGI
 *application* via the :meth:`pyramid.config.Configurator.make_wsgi_app`
@@ -230,7 +203,7 @@ WSGI Application Serving
 .. ignore-next-block
 .. literalinclude:: helloworld.py
    :linenos:
-   :lines: 12
+   :lines: 13
 
 Finally, we actually serve the application to requestors by starting up a
 WSGI server.  We happen to use the :func:`paste.httpserver.serve` WSGI server
@@ -243,9 +216,9 @@ from a local system.  We don't specify a TCP port number to listen on; this
 means we want to use the default TCP port, which is 8080.
 
 When this line is invoked, it causes the server to start listening on TCP
-port 8080.  It will serve requests forever, or at least until we stop it by
-killing the process which runs it (usually by pressing ``Ctrl-C`` in the
-terminal we used to start it).
+port 8080.  The server will serve requests forever, or at least until we stop
+it by killing the process which runs it (usually by pressing ``Ctrl-C`` in
+the terminal we used to start it).
 
 Conclusion
 ~~~~~~~~~~
diff --git a/docs/narr/helloworld.py b/docs/narr/helloworld.py
index ce0fcf955..92e16efbb 100644
--- a/docs/narr/helloworld.py
+++ b/docs/narr/helloworld.py
@@ -1,12 +1,13 @@
 from paste.httpserver import serve
 from pyramid.configuration import Configurator
+from pyramid.response import Response
 
 def hello_world(request):
-   return 'Hello %(name)s!' % request.matchdict
+   return Response('Hello %(name)s!' % request.matchdict)
 
 if __name__ == '__main__':
    config = Configurator()
    config.add_route('hello', '/hello/{name}')
-   config.add_view(hello_world, route_name='hello', renderer='string')
+   config.add_view(hello_world, route_name='hello')
    app = config.make_wsgi_app()
-   serve(app, host='0.0.0.0')
\ No newline at end of file
+   serve(app, host='0.0.0.0')