6 files changed, 98 insertions, 7 deletions
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index 0bfac946e..0fccba624 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -1,7 +1,7 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
-  <title>The Pyramid Web Application Development Framework</title>
+  <title>The Pyramid Web Framework</title>
   <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
   <meta name="keywords" content="python web application" />
   <meta name="description" content="pyramid web application" />
@@ -24,7 +24,7 @@
       <div class="middle align-center">
         <p class="app-welcome">
           Welcome to <span class="app-name">${project}</span>, an application generated by<br/>
-          the Pyramid web application development framework.
+          the Pyramid Web Framework.
         </p>
       </div>
     </div>
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 929208083..11af89ca6 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -53,7 +53,7 @@ method (see also :term:`Configurator`):
 
   from subscribers import mysubscriber
 
-  # "config" below is assumed to be an instance of a 
+  # "config" below is assumed to be an instance of a
   # pyramid.config.Configurator object
 
   config.add_subscriber(mysubscriber, NewRequest)
@@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function.
 
   @subscriber(NewRequest)
   def mysubscriber(event):
-	  event.request.foo = 1
+      event.request.foo = 1
 
 When the :func:`~pyramid.events.subscriber` decorator is used a
 :term:`scan` must be performed against the package containing the
@@ -113,7 +113,7 @@ your application like so:
    :linenos:
 
    def handle_new_request(event):
-       print 'request', event.request   
+       print 'request', event.request
 
    def handle_new_response(event):
        print 'response', event.response
@@ -150,3 +150,86 @@ application, because the interface defined at
 :class:`pyramid.interfaces.INewResponse` says it must
 (:class:`pyramid.events.NewResponse` objects also have a ``request``).
 
+.. _custom_events:
+
+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.
+
+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:
+
+.. code-block:: python
+   :linenos:
+
+    class DocCreated(object):
+        def __init__(self, doc, request):
+            self.doc = doc
+            self.request = request
+
+    class UserEvent(object):
+        def __init__(self, user):
+            self.user = user
+
+    class UserLoggedIn(UserEvent):
+        pass
+
+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:
+
+.. code-block:: python
+   :linenos:
+
+    from pyramid.events import subscriber
+    from .events import DocCreated
+    from .index import index_doc
+
+    @subscriber(DocCreated)
+    def index_doc(event):
+        # 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.
+
+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:
+
+    from .events import DocCreated
+
+    def new_doc_view(request):
+        doc = MyDoc()
+        event = DocCreated(doc, request)
+        request.registry.notify(event)
+        return {'document': doc}
+
+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.
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index e25f3012a..ec5d706aa 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -992,6 +992,8 @@ prompt with a similar configuration as would be loaded if you were running
 your Pyramid application via ``pserve``.  This can be a useful debugging tool.
 See :ref:`interactive_shell` for more details.
 
+.. _what_is_this_pserve_thing:
+
 What Is This ``pserve`` Thing
 -----------------------------
 
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 82440060c..358977089 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -188,6 +188,8 @@ implementation in the :mod:`pyramid.session` module as inspiration.
 .. index::
    single: flash messages
 
+.. _flash_messages:
+
 Flash Messages
 --------------
 
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index d4cf20b93..26bb6b6cd 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -616,6 +616,8 @@ extension so that these ``svn:ignore`` patterns work.
 .. index::
    pair: debugging; templates
 
+.. _debugging_templates:
+
 Debugging Templates
 -------------------
 
@@ -711,7 +713,7 @@ look like:
          <h1 class="title">Welcome to <code>${project}</code>, an
 	  application generated by the <a
 	  href="http://docs.pylonsproject.org/projects/pyramid/current/"
-         >pyramid</a> web application framework.</h1>
+         >pyramid</a> web framework.</h1>
       </body>
     </html>
 
@@ -723,7 +725,7 @@ This template doesn't use any advanced features of Mako, only the
 Using A Mako def name Within a Renderer Name
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sommetime you'd like to render a ``def`` inside of a Mako template instead of
+Sometimes you'd like to render a ``def`` inside of a Mako template instead of
 the full Mako template. To render a def inside a Mako template, given a
 :term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can
 configure the template as a :term:`renderer` like so:
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 6a064c209..e09fd83ab 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -1005,6 +1005,8 @@ invoked as the result of the ``http_cache`` argument to view configuration.
 .. index::
    pair: view configuration; debugging
 
+.. _debugging_view_configuration:
+
 Debugging View Configuration
 ----------------------------