- Reordered chapters in narrative section for better new user friendliness.

- Added more indexing markers to sections in documentation.

1 files changed, 25 insertions, 43 deletions

diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 1c9529860..a3fd61098 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -3,10 +3,10 @@
 Views
 =====
 
-One of the primary jobs of :app:`Pyramid` is to find and invoke a
-:term:`view callable` when a :term:`request` reaches your application.  View
-callables are bits of code which do something interesting in response to a
-request made to your application.
+One of the primary jobs of :app:`Pyramid` is to find and invoke a :term:`view
+callable` when a :term:`request` reaches your application.  View callables
+are bits of code which do something interesting in response to a request made
+to your application.  They are the "meat" of any interesting web application.
 
 .. note:: 
 
@@ -17,23 +17,10 @@ request made to your application.
    that implements a view *callable*, and the process of view
    *lookup*.
 
-The :ref:`urldispatch_chapter`, and :ref:`traversal_chapter` chapters
-describes how, using information from the :term:`request`, a
-:term:`context` resource is computed.  But the context resource itself
-isn't very useful without an associated :term:`view callable`.  A view
-callable returns a response to a user, often using the context resource
-to do so.
-
-The job of actually locating and invoking the "best" :term:`view callable` is
-the job of the :term:`view lookup` subsystem.  The view lookup subsystem
-compares the resource supplied by :term:`resource location` and information
-in the :term:`request` against :term:`view configuration` statements made by
-the developer to choose the most appropriate view callable for a specific
-set of circumstances.
-
-This chapter describes how view callables work. In the
-:ref:`view_config_chapter` chapter, there are details about performing
-view configuration, and a detailed explanation of view lookup.
+This chapter describes how view callables should be defined. We'll have to
+wait until a following chapter (entitled :ref:`view_config_chapter`) to find
+out how we actually tell :app:`Pyramid` to wire up view callables to
+particular URL patterns and other request circumstances.
 
 .. index::
    single: view callables
@@ -42,26 +29,20 @@ View Callables
 --------------
 
 View callables are, at the risk of sounding obvious, callable Python
-objects. Specifically, view callables can be functions, classes, or
-instances that implement an ``__call__`` method (making the
-instance callable).
+objects. Specifically, view callables can be functions, classes, or instances
+that implement an ``__call__`` method (making the instance callable).
 
 View callables must, at a minimum, accept a single argument named
 ``request``.  This argument represents a :app:`Pyramid` :term:`Request`
-object.  A request object encapsulates a WSGI environment provided to
-:app:`Pyramid` by the upstream :term:`WSGI` server. As you might expect,
-the request object contains everything your application needs to know
-about the specific HTTP request being made.
+object.  A request object represents a :term:`WSGI` environment provided to
+:app:`Pyramid` by the upstream WSGI server. As you might expect, the request
+object contains everything your application needs to know about the specific
+HTTP request being made.
 
 A view callable's ultimate responsibility is to create a :mod:`Pyramid`
-:term:`Response` object. This can be done by creating the response object in
-the view callable code and returning it directly, as we will be doing in this
-chapter. However, if a view callable does not return a response itself, it
-can be configured to use a :term:`renderer` that converts its return value
-into a :term:`Response` object. Using renderers is the common way that
-templates are used with view callables to generate markup: see the
-:ref:`renderers_chapter` chapter for details.  In some cases, a response may
-also be generated by raising an exception within a view callable.
+:term:`Response` object. This can be done by creating a :term:`Response`
+object in the view callable code and returning it directly or by raising
+special kinds of exceptions from within the body of a view callable.
 
 .. index::
    single: view calling convention
@@ -160,13 +141,14 @@ the class :class:`pyramid.httpexceptions.HTTPFound` is also a valid response
 object because it inherits from :class:`~pyramid.response.Response`.  For
 examples, see :ref:`http_exceptions` and :ref:`http_redirect`.
 
-You can also return objects from view callables that aren't instances of (or
-instances of classes which are subclasses of)
-:class:`pyramid.response.Response` in various circumstances.  This can be
-helpful when writing tests and when attempting to share code between view
-callables.  See :ref:`renderers_chapter` for the common way to allow for
-this.  A much less common way to allow for view callables to return
-non-Response objects is documented in :ref:`using_iresponse`.
+.. note::
+
+   You can also return objects from view callables that aren't instances of
+   :class:`pyramid.response.Response` in various circumstances.  This can be
+   helpful when writing tests and when attempting to share code between view
+   callables.  See :ref:`renderers_chapter` for the common way to allow for
+   this.  A much less common way to allow for view callables to return
+   non-Response objects is documented in :ref:`using_iresponse`.
 
 .. index::
    single: view exceptions