minor grammar, rewrap 79 cols, .rst syntax fixes

1 files changed, 73 insertions, 83 deletions

diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 09caac898..c10d4cc47 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -9,18 +9,18 @@
 .. _events_chapter:
 
 Using Events
-=============
+============
 
-An *event* is an object broadcast by the :app:`Pyramid` framework
-at interesting points during the lifetime of an application.  You
-don't need to use events in order to create most :app:`Pyramid`
-applications, but they can be useful when you want to perform slightly
-advanced operations.  For example, subscribing to an event can allow
-you to run some code as the result of every new request.
+An *event* is an object broadcast by the :app:`Pyramid` framework at
+interesting points during the lifetime of an application.  You don't need to
+use events in order to create most :app:`Pyramid` applications, but they can be
+useful when you want to perform slightly advanced operations.  For example,
+subscribing to an event can allow you to run some code as the result of every
+new request.
 
-Events in :app:`Pyramid` are always broadcast by the framework.
-However, they only become useful when you register a *subscriber*.  A
-subscriber is a function that accepts a single argument named `event`:
+Events in :app:`Pyramid` are always broadcast by the framework. However, they
+only become useful when you register a *subscriber*.  A subscriber is a
+function that accepts a single argument named `event`:
 
 .. code-block:: python
    :linenos:
@@ -28,23 +28,20 @@ subscriber is a function that accepts a single argument named `event`:
    def mysubscriber(event):
        print(event)
 
-The above is a subscriber that simply prints the event to the console
-when it's called.
+The above is a subscriber that simply prints the event to the console when it's
+called.
 
 The mere existence of a subscriber function, however, is not sufficient to
 arrange for it to be called.  To arrange for the subscriber to be called,
-you'll need to use the
-:meth:`pyramid.config.Configurator.add_subscriber` method or you'll
-need to use the :func:`pyramid.events.subscriber` decorator to decorate a
-function found via a :term:`scan`.
+you'll need to use the :meth:`pyramid.config.Configurator.add_subscriber`
+method or you'll need to use the :func:`pyramid.events.subscriber` decorator to
+decorate a function found via a :term:`scan`.
 
 Configuring an Event Listener Imperatively
 ------------------------------------------
 
-You can imperatively configure a subscriber function to be called
-for some event type via the
-:meth:`~pyramid.config.Configurator.add_subscriber`
-method:
+You can imperatively configure a subscriber function to be called for some
+event type via the :meth:`~pyramid.config.Configurator.add_subscriber` method:
 
 .. code-block:: python
   :linenos:
@@ -58,10 +55,9 @@ method:
 
   config.add_subscriber(mysubscriber, NewRequest)
 
-The first argument to
-:meth:`~pyramid.config.Configurator.add_subscriber` is the
-subscriber function (or a :term:`dotted Python name` which refers
-to a subscriber callable); the second argument is the event type.
+The first argument to :meth:`~pyramid.config.Configurator.add_subscriber` is
+the subscriber function (or a :term:`dotted Python name` which refers to a
+subscriber callable); the second argument is the event type.
 
 .. seealso::
 
@@ -70,8 +66,8 @@ to a subscriber callable); the second argument is the event type.
 Configuring an Event Listener Using a Decorator
 -----------------------------------------------
 
-You can configure a subscriber function to be called for some event
-type via the :func:`pyramid.events.subscriber` function.
+You can configure a subscriber function to be called for some event type via
+the :func:`pyramid.events.subscriber` function.
 
 .. code-block:: python
   :linenos:
@@ -83,9 +79,9 @@ type via the :func:`pyramid.events.subscriber` function.
   def mysubscriber(event):
       event.request.foo = 1
 
-When the :func:`~pyramid.events.subscriber` decorator is used a
-:term:`scan` must be performed against the package containing the
-decorated function for the decorator to have any effect.
+When the :func:`~pyramid.events.subscriber` decorator is used, a :term:`scan`
+must be performed against the package containing the decorated function for the
+decorator to have any effect.
 
 Either of the above registration examples implies that every time the
 :app:`Pyramid` framework emits an event object that supplies an
@@ -96,13 +92,12 @@ As you can see, a subscription is made in terms of a *class* (such as
 :class:`pyramid.events.NewResponse`).  The event object sent to a subscriber
 will always be an object that possesses an :term:`interface`.  For
 :class:`pyramid.events.NewResponse`, that interface is
-:class:`pyramid.interfaces.INewResponse`. The interface documentation
-provides information about available attributes and methods of the event
-objects.
+:class:`pyramid.interfaces.INewResponse`. The interface documentation provides
+information about available attributes and methods of the event objects.
 
-The return value of a subscriber function is ignored.  Subscribers to
-the same event type are not guaranteed to be called in any particular
-order relative to each other.
+The return value of a subscriber function is ignored.  Subscribers to the same
+event type are not guaranteed to be called in any particular order relative to
+each other.
 
 All the concrete :app:`Pyramid` event types are documented in the
 :ref:`events_module` API documentation.
@@ -110,8 +105,8 @@ All the concrete :app:`Pyramid` event types are documented in the
 An Example
 ----------
 
-If you create event listener functions in a ``subscribers.py`` file in
-your application like so:
+If you create event listener functions in a ``subscribers.py`` file in your
+application like so:
 
 .. code-block:: python
    :linenos:
@@ -122,9 +117,8 @@ your application like so:
    def handle_new_response(event):
        print('response', event.response)
 
-You may configure these functions to be called at the appropriate
-times by adding the following code to your application's
-configuration startup:
+You may configure these functions to be called at the appropriate times by
+adding the following code to your application's configuration startup:
 
 .. code-block:: python
    :linenos:
@@ -136,22 +130,21 @@ configuration startup:
    config.add_subscriber('myproject.subscribers.handle_new_response',
                          'pyramid.events.NewResponse')
 
-Either mechanism causes the functions in ``subscribers.py`` to be
-registered as event subscribers.  Under this configuration, when the
-application is run, each time a new request or response is detected, a
-message will be printed to the console.
+Either mechanism causes the functions in ``subscribers.py`` to be registered as
+event subscribers.  Under this configuration, when the application is run, each
+time a new request or response is detected, a message will be printed to the
+console.
 
-Each of our subscriber functions accepts an ``event`` object and
-prints an attribute of the event object.  This begs the question: how
-can we know which attributes a particular event has?
+Each of our subscriber functions accepts an ``event`` object and prints an
+attribute of the event object.  This begs the question: how can we know which
+attributes a particular event has?
 
 We know that :class:`pyramid.events.NewRequest` event objects have a
-``request`` attribute, which is a :term:`request` object, because the
-interface defined at :class:`pyramid.interfaces.INewRequest` says it must.
-Likewise, we know that :class:`pyramid.interfaces.NewResponse` events have a
-``response`` attribute, which is a response object constructed by your
-application, because the interface defined at
-:class:`pyramid.interfaces.INewResponse` says it must
+``request`` attribute, which is a :term:`request` object, because the interface
+defined at :class:`pyramid.interfaces.INewRequest` says it must. Likewise, we
+know that :class:`pyramid.interfaces.NewResponse` events have a ``response``
+attribute, which is a response object constructed by your application, because
+the interface defined at :class:`pyramid.interfaces.INewResponse` says it must
 (:class:`pyramid.events.NewResponse` objects also have a ``request``).
 
 .. _custom_events:
@@ -159,21 +152,20 @@ application, because the interface defined at
 Creating Your Own Events
 ------------------------
 
-In addition to using the events that the Pyramid framework creates,
-you can create your own events for use in your application. This can
-be useful to decouple parts of your application.
+In addition to using the events that the Pyramid framework creates, you can
+create your own events for use in your application. This can be useful to
+decouple parts of your application.
 
-For example, suppose your application has to do many things when a new
-document is created. Rather than putting all this logic in the view
-that creates the document, you can create the document in your view
-and then fire a custom event. Subscribers to the custom event can take
-other actions, such as indexing the document, sending email, or
-sending a message to a remote system.
+For example, suppose your application has to do many things when a new document
+is created. Rather than putting all this logic in the view that creates the
+document, you can create the document in your view and then fire a custom
+event. Subscribers to the custom event can take other actions, such as indexing
+the document, sending email, or sending a message to a remote system.
 
-An event is simply an object. There are no required attributes or
-method for your custom events. In general, your events should keep
-track of the information that subscribers will need. Here are some
-example custom event classes:
+An event is simply an object. There are no required attributes or method for
+your custom events. In general, your events should keep track of the
+information that subscribers will need. Here are some example custom event
+classes:
 
 .. code-block:: python
     :linenos:
@@ -193,11 +185,10 @@ example custom event classes:
 Some Pyramid applications choose to define custom events classes in an
 ``events`` module.
 
-You can subscribe to custom events in the same way that you subscribe
-to Pyramid events -- either imperatively or with a decorator. You can
-also use custom events with :ref:`subscriber predicates
-<subscriber_predicates>`. Here's an example of subscribing to a custom
-event with a decorator:
+You can subscribe to custom events in the same way that you subscribe to
+Pyramid events—either imperatively or with a decorator. You can also use custom
+events with :ref:`subscriber predicates <subscriber_predicates>`. Here's an
+example of subscribing to a custom event with a decorator:
 
 .. code-block:: python
     :linenos:
@@ -211,12 +202,12 @@ event with a decorator:
         # index the document using our application's index_doc function
         index_doc(event.doc, event.request)
 
-The above example assumes that the application defines a
-``DocCreated`` event class and an ``index_doc`` function.
+The above example assumes that the application defines a ``DocCreated`` event
+class and an ``index_doc`` function.
 
-To fire your custom events use the
-:meth:`pyramid.registry.Registry.notify` method, which is most often
-accessed as ``request.registry.notify``. For example:
+To fire your custom events use the :meth:`pyramid.registry.Registry.notify`
+method, which is most often accessed as ``request.registry.notify``. For
+example:
 
 .. code-block:: python
     :linenos:
@@ -229,11 +220,10 @@ accessed as ``request.registry.notify``. For example:
         request.registry.notify(event)
         return {'document': doc}
 
-This example view will notify all subscribers to the custom
-``DocCreated`` event.
+This example view will notify all subscribers to the custom ``DocCreated``
+event.
 
-Note that when you fire an event, all subscribers are run
-synchronously so it's generally not a good idea
-to create event handlers that may take a long time to run. Although
-event handlers could be used as a central place to spawn tasks on your
-own message queues.
+Note that when you fire an event, all subscribers are run synchronously so it's
+generally not a good idea to create event handlers that may take a long time to
+run. Although event handlers could be used as a central place to spawn tasks on
+your own message queues.