convert narrative docs to Pyramid

1 files changed, 50 insertions, 50 deletions

diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index deac69fda..16410d07f 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -1,9 +1,9 @@
 .. _firstapp_chapter:
 
-Creating Your First :mod:`repoze.bfg` Application
+Creating Your First :mod:`pyramid` Application
 =================================================
 
-We will walk through the creation of a tiny :mod:`repoze.bfg`
+We will walk through the creation of a tiny :mod:`pyramid`
 application in this chapter.  After we're finished creating it, we'll
 explain in more detail how the application works.
 
@@ -20,7 +20,7 @@ explain in more detail how the application works.
 Hello World, Goodbye World (Imperative)
 ---------------------------------------
 
-Here's one of the very simplest :mod:`repoze.bfg` applications,
+Here's one of the very simplest :mod:`pyramid` applications,
 configured imperatively:
 
 .. code-block:: python
@@ -28,7 +28,7 @@ configured imperatively:
 
    from webob import Response
    from paste.httpserver import serve
-   from repoze.bfg.configuration import Configurator
+   from pyramid.configuration import Configurator
 
    def hello_world(request):
        return Response('Hello world!')
@@ -47,7 +47,7 @@ configured imperatively:
 
 When this code is inserted into a Python script named
 ``helloworld.py`` and executed by a Python interpreter which has the
-:mod:`repoze.bfg` software installed, an HTTP server is started on TCP
+:mod:`pyramid` software installed, an HTTP server is started on TCP
 port 8080.  When port 8080 is visited by a browser on the root URL
 (``/``), the server will simply serve up the text "Hello world!"  When
 visited by a browser on the URL ``/goodbye``, the server will serve up
@@ -66,24 +66,24 @@ The above script defines the following set of imports:
 
    from webob import Response
    from paste.httpserver import serve
-   from repoze.bfg.configuration import Configurator
+   from pyramid.configuration import Configurator
 
-:mod:`repoze.bfg` uses the :term:`WebOb` library as the basis for its
+:mod:`pyramid` uses the :term:`WebOb` library as the basis for its
 :term:`request` and :term:`response` objects.  The script uses the
 :class:`webob.Response` class later in the script to create a
 :term:`response` object.
 
-Like many other Python web frameworks, :mod:`repoze.bfg` uses the
+Like many other Python web frameworks, :mod:`pyramid` uses the
 :term:`WSGI` protocol to connect an application and a web server
 together.  The :mod:`paste.httpserver` server is used in this example
 as a WSGI server for convenience, as the ``paste`` package is a
-dependency of :mod:`repoze.bfg` itself.
+dependency of :mod:`pyramid` itself.
 
 The script also imports the ``Configurator`` class from the
-``repoze.bfg.configuration`` module.  This class is used to configure
-:mod:`repoze.bfg` for a particular application.  An instance of this
+``pyramid.configuration`` module.  This class is used to configure
+:mod:`pyramid` for a particular application.  An instance of this
 class provides methods which help configure various parts of
-:mod:`repoze.bfg` for a given application deployment.
+:mod:`pyramid` for a given application deployment.
 
 View Callable Declarations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -107,7 +107,7 @@ The ``goodbye_world`` function returns a response instance with the
 body ``Goodbye world!``.
 
 Each of these functions is known as a :term:`view callable`.  View
-callables in a :mod:`repoze.bfg` application accept a single argument,
+callables in a :mod:`pyramid` application accept a single argument,
 ``request`` and are expected to return a :term:`response` object.  A
 view callable doesn't need to be a function; it can be represented via
 another type of object, like a class or an instance, but for our
@@ -115,7 +115,7 @@ purposes here, a function serves us well.
 
 A view callable is always called with a :term:`request` object.  A
 request object is a representation of an HTTP request sent to
-:mod:`repoze.bfg` via the active :term:`WSGI` server.
+:mod:`pyramid` via the 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
@@ -182,9 +182,9 @@ code within the ``if`` block should only be run during a direct script
 execution.
 
 The ``config = Configurator()`` line above creates an instance of the
-:class:`repoze.bfg.configuration.Configurator` class.  The resulting
+:class:`pyramid.configuration.Configurator` class.  The resulting
 ``config`` object represents an API which the script uses to configure
-this particular :mod:`repoze.bfg` application.  Methods called on the
+this particular :mod:`pyramid` application.  Methods called on the
 Configurator will cause registrations to be made in a
 :term:`application registry` associated with the application.
 
@@ -196,7 +196,7 @@ Beginning Configuration
 
    config.begin()
 
-The :meth:`repoze.bfg.configuration.Configurator.begin` method tells
+The :meth:`pyramid.configuration.Configurator.begin` method tells
 the system that application configuration has begun.  In particular,
 this causes the :term:`application registry` associated with this
 configurator to become the "current" application registry, meaning
@@ -224,7 +224,7 @@ Adding Configuration
    config.add_view(goodbye_world, name='goodbye')
 
 Each of these lines calls the
-:meth:`repoze.bfg.configuration.Configurator.add_view` method.  The
+:meth:`pyramid.configuration.Configurator.add_view` method.  The
 ``add_view`` method of a configurator registers a :term:`view
 configuration` within the :term:`application registry`.  A :term:`view
 configuration` represents a set of circumstances related to the
@@ -241,7 +241,7 @@ argument passed is the ``hello_world`` function.  This line calls
 ``add_view`` with a *default* value for the :term:`predicate`
 argument, named ``name``.  The ``name`` predicate defaults to a value
 equalling the empty string (``''``).  This means that we're
-instructing :mod:`repoze.bfg` to invoke the ``hello_world`` view
+instructing :mod:`pyramid` to invoke the ``hello_world`` view
 callable when the :term:`view name` is the empty string.  We'll learn
 in later chapters what a :term:`view name` is, and under which
 circumstances a request will have a view name that is the empty
@@ -266,17 +266,17 @@ 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 :mod:`repoze.bfg` processes a
+of its associated view callable.  When :mod:`pyramid` processes a
 request, however, 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, :mod:`repoze.bfg` chooses the most specific view
+In this application, :mod:`pyramid` chooses the most specific view
 callable based only on view :term:`predicate` applicability.  The
 ordering of calls to
-:meth:`repoze.bfg.configuration.Configurator.add_view` is never very
+:meth:`pyramid.configuration.Configurator.add_view` is never very
 important.  We can register ``goodbye_world`` first and
-``hello_world`` second; :mod:`repoze.bfg` will still give us the most
+``hello_world`` second; :mod:`pyramid` will still give us the most
 specific callable when a request is dispatched to it.
 
 Ending Configuration
@@ -287,9 +287,9 @@ Ending Configuration
 
    config.end()
 
-The :meth:`repoze.bfg.configuration.Configurator.end` method tells the
+The :meth:`pyramid.configuration.Configurator.end` method tells the
 system that application configuration has ended.  It is the inverse of
-:meth:`repoze.bfg.configuration.Configurator.begin`.  In particular,
+:meth:`pyramid.configuration.Configurator.begin`.  In particular,
 this causes the :term:`application registry` associated with this
 configurator to no longer be the "current" application registry,
 meaning that code which attempts to use the application registry
@@ -315,7 +315,7 @@ WSGI Application Creation
 
 After configuring views and ending configuration, the script creates a
 WSGI *application* via the
-:meth:`repoze.bfg.configuration.Configurator.make_wsgi_app` method.  A
+:meth:`pyramid.configuration.Configurator.make_wsgi_app` method.  A
 call to ``make_wsgi_app`` implies that all configuration is finished
 (meaning all method calls to the configurator which set up views, and
 various other configuration settings have been performed).  The
@@ -326,8 +326,8 @@ Python applications.  We don't discuss :term:`WSGI` in any depth
 within this book, however, you can learn more about it by visiting
 `wsgi.org <http://wsgi.org>`_.
 
-The :mod:`repoze.bfg` application object, in particular, is an
-instance of a class representing a :mod:`repoze.bfg` :term:`router`.
+The :mod:`pyramid` application object, in particular, is an
+instance of a class representing a :mod:`pyramid` :term:`router`.
 It has a reference to the :term:`application registry` which resulted
 from method calls to the configurator used to configure it.  The
 :term:`router` consults the registry to obey the policy choices made
@@ -363,7 +363,7 @@ Conclusion
 ~~~~~~~~~~
 
 Our hello world application is one of the simplest possible
-:mod:`repoze.bfg` applications, configured "imperatively".  We can see
+:mod:`pyramid` applications, configured "imperatively".  We can see
 that it's configured imperatively because the full power of Python is
 available to us as we perform configuration tasks.
 
@@ -376,7 +376,7 @@ Hello World, Goodbye World (Declarative)
 ----------------------------------------
 
 Another almost entirely equivalent mode of application configuration
-exists named *declarative* configuration.  :mod:`repoze.bfg` can be
+exists named *declarative* configuration.  :mod:`pyramid` can be
 configured for the same "hello world" application "declaratively", if
 so desired.
 
@@ -387,7 +387,7 @@ To do so, first, create a file named ``helloworld.py``:
 
    from webob import Response
    from paste.httpserver import serve
-   from repoze.bfg.configuration import Configurator
+   from pyramid.configuration import Configurator
 
    def hello_world(request):
        return Response('Hello world!')
@@ -409,9 +409,9 @@ the previously created ``helloworld.py``:
 .. code-block:: xml
    :linenos:
 
-   <configure xmlns="http://namespaces.repoze.org/bfg">
+   <configure xmlns="http://pylonshq.com/pyramid">
 
-     <include package="repoze.bfg.includes" />
+     <include package="pyramid.includes" />
 
      <view
         view="helloworld.hello_world"
@@ -445,7 +445,7 @@ within the ``if __name__ == '__main__'`` section of ``helloworld.py``:
        serve(app, host='0.0.0.0')
 
 In our "declarative" code, we've added a call to the
-:meth:`repoze.bfg.configuration.Configurator.load_zcml` method with
+:meth:`pyramid.configuration.Configurator.load_zcml` method with
 the value ``configure.zcml``, and we've removed the lines which read
 ``config.add_view(hello_world)`` and ``config.add_view(goodbye_world,
 name='goodbye')``, so that it now reads as:
@@ -471,9 +471,9 @@ which sits next to ``helloworld.py``.  Let's take a look at the
 .. code-block:: xml
    :linenos:
 
-   <configure xmlns="http://namespaces.repoze.org/bfg">
+   <configure xmlns="http://pylonshq.com/pyramid">
 
-      <include package="repoze.bfg.includes" />
+      <include package="pyramid.includes" />
 
       <view
          view="helloworld.hello_world"
@@ -499,14 +499,14 @@ The ``configure.zcml`` ZCML file contains this bit of XML:
 .. code-block:: xml
    :linenos:
 
-    <configure xmlns="http://namespaces.repoze.org/bfg">
+    <configure xmlns="http://pylonshq.com/pyramid">
 
        <!-- other directives -->
 
     </configure>
 
 Because :term:`ZCML` is XML, and because XML requires a single root
-tag for each document, every ZCML file used by :mod:`repoze.bfg` must
+tag for each document, every ZCML file used by :mod:`pyramid` must
 contain a ``configure`` container directive, which acts as the root
 XML tag.  It is a "container" directive because its only job is to
 contain other directives.
@@ -521,18 +521,18 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the
 
 .. code-block:: xml
 
-   <include package="repoze.bfg.includes" />
+   <include package="pyramid.includes" />
 
-This self-closing tag instructs :mod:`repoze.bfg` to load a ZCML file
+This self-closing tag instructs :mod:`pyramid` to load a ZCML file
 from the Python package with the :term:`dotted Python name`
-``repoze.bfg.includes``, as specified by its ``package`` attribute.
+``pyramid.includes``, as specified by its ``package`` attribute.
 This particular ``<include>`` declaration is required because it
 actually allows subsequent declaration tags (such as ``<view>``, which
 we'll see shortly) to be recognized.  The ``<include>`` tag
 effectively just includes another ZCML file, causing its declarations
 to be executed.  In this case, we want to load the declarations from
 the file named ``configure.zcml`` within the
-:mod:`repoze.bfg.includes` Python package.  We know we want to load
+:mod:`pyramid.includes` Python package.  We know we want to load
 the ``configure.zcml`` from this package because ``configure.zcml`` is
 the default value for another attribute of the ``<include>`` tag named
 ``file``.  We could have spelled the include tag more verbosely, but
@@ -541,16 +541,16 @@ equivalently as:
 .. code-block:: xml
    :linenos:
 
-   <include package="repoze.bfg.includes" 
+   <include package="pyramid.includes" 
             file="configure.zcml"/>
 
 The ``<include>`` tag that includes the ZCML statements implied by the
 ``configure.zcml`` file from the Python package named
-:mod:`repoze.bfg.includes` is basically required to come before any
+:mod:`pyramid.includes` is basically required to come before any
 other named declaration in an application's ``configure.zcml``.  If it
 is not included, subsequent declaration tags will fail to be
 recognized, and the configuration system will generate an error at
-startup.  However, the ``<include package="repoze.bfg.includes"/>``
+startup.  However, the ``<include package="pyramid.includes"/>``
 tag needs to exist only in a "top-level" ZCML file, it needn't also
 exist in ZCML files *included by* a top-level ZCML file.
 
@@ -574,7 +574,7 @@ The ``configure.zcml`` ZCML file contains these bits of XML *after* the
      view="helloworld.goodbye_world"
      />
 
-These ``<view>`` declaration tags direct :mod:`repoze.bfg` to create
+These ``<view>`` declaration tags direct :mod:`pyramid` to create
 two :term:`view configuration` registrations.  The first ``<view>``
 tag has an attribute (the attribute is also named ``view``), which
 points at a :term:`dotted Python name`, referencing the
@@ -600,13 +600,13 @@ configurations imperatively, we saw this code:
    config.add_view(goodbye_world, name='goodbye')
 
 Each ``<view>`` declaration tag encountered in a ZCML file effectively
-invokes the :meth:`repoze.bfg.configuration.Configurator.add_view`
+invokes the :meth:`pyramid.configuration.Configurator.add_view`
 method on the behalf of the developer.  Various attributes can be
 specified on the ``<view>`` tag which influence the :term:`view
 configuration` it creates.
 
 Since the relative ordering of calls to
-:meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter
+:meth:`pyramid.configuration.Configurator.add_view` doesn't matter
 (see the sidebar entitled *View Dispatch and Ordering* within
 :ref:`adding_configuration`), the relative order of ``<view>`` tags in
 ZCML doesn't matter either.  The following ZCML orderings are
@@ -640,7 +640,7 @@ completely equivalent:
        view="helloworld.hello_world"
        />
 
-We've now configured a :mod:`repoze.bfg` helloworld application
+We've now configured a :mod:`pyramid` helloworld application
 declaratively.  More information about this mode of configuration is
 available in :ref:`declarative_configuration` and within
 :ref:`zcml_reference`.
@@ -649,7 +649,7 @@ References
 ----------
 
 For more information about the API of a :term:`Configurator` object,
-see :class:`repoze.bfg.configuration.Configurator` .  The equivalent
+see :class:`pyramid.configuration.Configurator` .  The equivalent
 ZCML declaration tags are introduced in :ref:`zcml_reference`.
 
 For more information about :term:`view configuration`, see