Rendering cleanups.

author: Chris McDonough <chrism@agendaless.com> 2009-12-27 15:32:14 +0000
committer: Chris McDonough <chrism@agendaless.com> 2009-12-27 15:32:14 +0000
commit: e4e3aa3449d3ae390402a9cead205626816a2938 (patch)
tree: cdab3582902124055fedfb3d0320157c983638fe /docs/narr
parent: 878328bdfc3b5ac832f1728e4a0461e3129cf8d4 (diff)
download: pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.tar.gz
pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.tar.bz2
pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.zip
12 files changed, 122 insertions, 109 deletions
diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt
index b94cb7098..72e4fec9d 100644
--- a/docs/narr/MyProject/myproject/templates/mytemplate.pt
+++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt
@@ -1,4 +1,5 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!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"
       xmlns:tal="http://xml.zope.org/namespaces/tal">
 <head>
diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 73027e4c2..738295842 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -766,9 +766,9 @@ configuration` it creates.
 
 Since the relative ordering of calls to
 :meth:`repoze.bfg.configuration.Configurator.add_view` doesn't matter
-(see the sidebar above entitled *View Dispatch and Ordering*), the
-relative order of ``<view>`` tags in ZCML doesn't matter either.  The
-following ZCML orderings are completely equivalent:
+(see the sidebar entitled *View Dispatch and Ordering*), the relative
+order of ``<view>`` tags in ZCML doesn't matter either.  The following
+ZCML orderings are completely equivalent:
 
 .. topic:: Hello Before Goodbye
 
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index e4eb284f9..4fa0ef1d8 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -84,7 +84,6 @@ same system, to install a Python 2.5 interpreter from *source*, use
 the following commands:
 
 .. code-block:: text
-   :linenos:
 
    [chrism@vitaminf ~]$ cd ~
    [chrism@vitaminf ~]$ mkdir tmp
@@ -128,7 +127,6 @@ setuptools`` within the Python interpreter you'd like to run
 :mod:`repoze.bfg` under:
 
 .. code-block:: text
-   :linenos:
 
    [chrism@vitaminf bfg]$ python
    Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
@@ -195,7 +193,6 @@ can actually create a virtual environment.  To do so, invoke the
 following:
 
 .. code-block:: text
-   :linenos:
 
    $ virtualenv --no-site-packages bfgenv
    New python executable in bfgenv/bin/python
@@ -225,7 +222,6 @@ After you've got your ``bfgenv`` virtualenv installed, you may install
 virtualenv (``bfgenv``) directory:
 
 .. code-block:: text
-   :linenos:
 
    $ bin/easy_install -i http://dist.repoze.org/bfg/1.1/simple repoze.bfg
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 09b690a12..6b5494d76 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -117,19 +117,18 @@ Differences from Other Web Frameworks
 -------------------------------------
 
 Like :term:`Zope`, the :mod:`repoze.bfg` framework imposes more
-`control inversion <http://plope.com/control_inversion>`_ upon
-application developers than other Python frameworks such as
-:term:`Pylons`.  For example :mod:`repoze.bfg` allows you to
-explicitly resolve a URL to a :term:`context` object before invoking a
-:term:`view`.  Pylons and other Python "MVC" frameworks have no such
-intermediate step; they resolve a URL directly to a "controller".
-Another example: using the :mod:`repoze.bfg` security subsystem
-assumes that you're willing to attach an :term:`ACL` to a
-:term:`context` object; the ACL is checked by the framework itself
-instead of by user code, and access is permitted or denied by the
-framework itself rather than by user code.  Such a task would
-typically be performed by user-space decorators in other Python web
-frameworks.
+*control inversion* upon application developers than other Python
+frameworks such as :term:`Pylons`.  For example :mod:`repoze.bfg`
+allows you to explicitly resolve a URL to a :term:`context` object
+before invoking a :term:`view`.  Pylons and other Python "MVC"
+frameworks have no such intermediate step; they resolve a URL directly
+to a "controller".  Another example: using the :mod:`repoze.bfg`
+security subsystem assumes that you're willing to attach an
+:term:`ACL` to a :term:`context` object; the ACL is checked by the
+framework itself instead of by user code, and access is permitted or
+denied by the framework itself rather than by user code.  Such a task
+would typically be performed by user-space decorators in other Python
+web frameworks.
 
 Like Zope, but unlike :term:`Pylons` applications or most
 :term:`Django` applications, when you build a :mod:`repoze.bfg`
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index fd0ab27a1..2fe5489e2 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -29,8 +29,7 @@ To start a :mod:`repoze.bfg` :term:`project`, use the ``paster
 create`` facility using the interpreter from the virtualenv
 (``bfgenv``) directory you created in :ref:`installing_chapter`.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ bin/paster create -t bfg_starter
 
@@ -39,8 +38,7 @@ project.  You should use a string without spaces and with only letters
 in it.  Here's sample output from a run of ``paster create`` for a
 project we name ``MyProject``:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ bin/paster create -t bfg_starter
    Selected and implied templates:
@@ -128,15 +126,13 @@ the project directory.  The file named ``setup.py`` will be in the
 root of the paster-generated project directory.  The ``python`` you're
 invoking should be the one from your virtualenv.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py develop
 
 Elided output from a run of this command is shown below:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py develop
    ...
@@ -152,15 +148,13 @@ Running The Tests For Your Application
 To run unit tests for your application, you should invoke them like
 so:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/python setup.py test -q
 
 Here's sample output from a test run:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ python setup.py test -q
    running test
@@ -209,21 +203,18 @@ section within the ``.ini`` file.  For example, if your application
 If so, you can use the following command to invoke a debug shell using
 the name ``main`` as a section name:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
 
-    Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
-    [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
-    Type "help" for more information. "root" is the BFG app root object.
-    >>> root
-    <foo.models.MyModel object at 0x445270>
+   Python 2.4.5 (#1, Aug 29 2008, 12:27:37) 
+   [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
+   Type "help" for more information. "root" is the BFG app root object.
+   >>> root
+   <foo.models.MyModel object at 0x445270>
 
 .. note:: You *might* get away without passing
-          ``--plugin=repoze.bfg`` to the bfgshell command; the
-          ``--plugin=repoze.bfg`` option is only required under
-          conditions that are not yet well-understood.
+          ``--plugin=repoze.bfg`` to the bfgshell command.
 
 If you have `IPython <http://en.wikipedia.org/wiki/IPython>`_
 installed in the interpreter you use to invoke the ``paster`` command,
@@ -233,10 +224,9 @@ happen, even if you have IPython installed, you can pass the
 ``--disable-ipython`` flag to the ``bfgshell`` command to use a
 standard Python interpreter shell unconditionally.
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini main
 
 Press "Ctrl-D" to exit the interactive shell.
 
@@ -263,10 +253,9 @@ following ``.ini`` file content:
 
 The command you use to invoke the interactive shell should be:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
-    [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp
+   [chrism@vitaminf bfgshellenv]$ ../bin/paster --plugin=repoze.bfg bfgshell MyProject.ini myapp
 
 If you use ``main`` as the section name argument instead of ``myapp``
 against the above ``.ini`` file, an error will likely occur.  Use the
@@ -290,15 +279,13 @@ the generated ``MyProject.ini`` configuration file:
    webserver, as exception and debugging output will be sent to the
    console.
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ ../bin/paster serve MyProject.ini
 
 Here's sample output from a run:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    $ paster serve MyProject.ini
    Starting server in PID 16601.
diff --git a/docs/narr/scanning.rst b/docs/narr/scanning.rst
index a7f47efd4..2226b557f 100644
--- a/docs/narr/scanning.rst
+++ b/docs/narr/scanning.rst
@@ -76,7 +76,6 @@ effectively:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(hello, name='hello', request_method='GET')
 
diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst
index f4904f0bf..4e806ec17 100644
--- a/docs/narr/startup.rst
+++ b/docs/narr/startup.rst
@@ -6,7 +6,7 @@ Startup
 When you cause :mod:`repoze.bfg` to start up in a console window,
 you'll see something much like this show up on the console:
 
-.. code-block:: bash
+.. code-block:: text
 
   $ paster serve myproject/MyProject.ini
   Starting server in PID 16601.
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index 1683b3cef..3476622d5 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -82,8 +82,7 @@ This inexperienced user's attempt to execute ``cat`` against the file
 named ``/fiz/buz/myfile`` might be to issue the following set of UNIX
 commands:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
    cd /
    cd fiz
@@ -94,8 +93,7 @@ The user now know he has found a *file*, because the ``cd`` command
 issues an error when he executed ``cd myfile``.  Now he knows that he
 can run the ``cat`` command:
 
-.. code-block::  bash
-   :linenos:
+.. code-block::  text
 
    cat myfile
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 443ffbfaa..2d74bfbca 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -62,14 +62,9 @@ registry`.  Here's an example:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_route('myroute', '/prefix/:one/:two')
 
-See the :meth:`repoze.bfg.configuration.Configurator.add_route` API
-documentation for more information and options for adding a route
-imperatively.
-
 Configuring a Route via ZCML
 ----------------------------
 
@@ -109,13 +104,17 @@ The path pattern syntax is simple.
 
 The path may start with a slash character.  If the path does not start
 with a slash character, an implicit slash will be prepended to it at
-matching time.  For example, the following paths are equivalent::
+matching time.  For example, the following paths are equivalent:
+
+.. code-block:: text
 
-    :foo/bar/baz
+   :foo/bar/baz
 
-and::
+and:
 
-     /:foo/bar/baz
+.. code-block:: text
+
+   /:foo/bar/baz
 
 A path segment (an individual item between ``/`` characters in the
 path) may either be a literal string (e.g. ``foo``) *or* it may
@@ -123,17 +122,23 @@ segment replacement marker (e.g. ``:foo``).  A segment replacement
 marker is in the format ``:name``, where this means "accept any
 characters up to the next slash and use this as the ``name`` matchdict
 value."  For example, the following pattern defines one literal
-segment ("foo") and two dynamic segments ("baz", and "bar")::
+segment ("foo") and two dynamic segments ("baz", and "bar"):
+
+.. code-block:: text
 
-    foo/:baz/:bar
+   foo/:baz/:bar
 
 The above pattern will match these URLs, generating the following
-matchdicts::
+matchdicts:
+
+.. code-block:: text
 
    foo/1/2        -> {'baz':u'1', 'bar':u'2'}
    foo/abc/def    -> {'baz':u'abc', 'bar':u'2'}
 
-It will not match the following patterns however::
+It will not match the following patterns however:
+
+.. code-block:: text
 
    foo/1/2/        -> No match (trailing slash)
    bar/abc/def     -> First segment literal mismatch
@@ -141,28 +146,38 @@ It will not match the following patterns however::
 Note that values representing path segments matched with a
 ``:segment`` match will be url-unquoted and decoded from UTF-8 into
 Unicode within the matchdict.  So for instance, the following
-pattern::
+pattern:
+
+.. code-block:: text
+
+   foo/:bar
 
-    foo/:bar
+When matching the following URL:
 
-When matching the following URL::
+.. code-block:: text
 
-    foo/La%20Pe%C3%B1a
+   foo/La%20Pe%C3%B1a
 
 The matchdict will look like so (the value is URL-decoded / UTF-8
-decoded)::
+decoded):
 
-  {'bar':u'La Pe\xf1a'}
+.. code-block:: text
+
+   {'bar':u'La Pe\xf1a'}
 
 If the pattern has a ``*`` in it, the name which follows it is
 considered a "remainder match".  A remainder match *must* come at the
 end of the path pattern.  Unlike segment replacement markers, it does
-not need to be preceded by a slash.  For example::
+not need to be preceded by a slash.  For example:
+
+.. code-block:: text
 
-    foo/:baz/:bar*traverse
+   foo/:baz/:bar*traverse
 
 The above pattern will match these URLs, generating the following
-matchdicts::
+matchdicts:
+
+.. code-block:: text
 
    foo/1/2/               -> {'baz':1, 'bar':2, 'traverse':()}
    foo/abc/def/a/b/c      -> {'baz':abc, 'bar':2, 'traverse':('a', 'b', 'c')}
@@ -171,17 +186,23 @@ Note that when a ``*stararg`` remainder match is matched, the value
 put into the matchdict is turned into a tuple of path segments
 representing the remainder of the path.  These path segments are
 url-unquoted and decoded from UTF-8 into Unicode.  For example, for
-the following pattern::
+the following pattern:
+
+.. code-block:: text
+
+   foo/*traverse
 
-    foo/*traverse
+When matching the following path:
 
-When matching the following path::
+.. code-block:: text
 
-    /foo/La%20Pe%C3%B1a/a/b/c
+   /foo/La%20Pe%C3%B1a/a/b/c
 
-Will generate the following matchdict::
+Will generate the following matchdict:
 
-  {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
+.. code-block:: text
+
+   {'traverse':(u'La Pe\xf1a', u'a', u'b', u'c')}
 
 ``<route>`` Statement Examples
 ------------------------------
@@ -283,8 +304,7 @@ might add to your ``configure.zcml``:
 The above configuration will allow :mod:`repoze.bfg` to service URLs
 in these forms:
 
-.. code-block:: bash
-   :linenos:
+.. code-block:: text
 
    /ideas/<ideaname>
    /users/<username>
@@ -436,6 +456,7 @@ this.
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
    from repoze.bfg.url import route_url
    url = route_url('foo', request, a='1', b='2', c='3')
@@ -529,6 +550,7 @@ be removed after each request.  Put the following in the
 
 .. ignore-next-block
 .. code-block:: python
+   :linenos:
 
     from mypackage.sql import DBSession
 
diff --git a/docs/narr/urlmapping.rst b/docs/narr/urlmapping.rst
index 2eeaa0646..e5933ae1e 100644
--- a/docs/narr/urlmapping.rst
+++ b/docs/narr/urlmapping.rst
@@ -38,10 +38,12 @@ item "below" ``members`` in the URL represents a member in the system.
 You just match everything "below" ``members`` to a particular view.
 
 For example, you might configure a :term:`route` to match against the
-following URL patterns::
+following URL patterns:
 
-  archives/:year/:month/:day
-  members/:membername
+.. code-block:: text
+
+   archives/:year/:month/:day
+   members/:membername
 
 In this configuration, there are exactly two types of URLs that will
 match views in your application: ones that start with ``/archives``
@@ -50,10 +52,12 @@ day.  And ones that start with ``/members`` which are followed by a
 path segment containing a member's name.  This is very simple.
 
 :term:`URL dispatch` is not very good, however, at inferring the
-difference between sets of URLs such as::
+difference between sets of URLs such as:
+
+.. code-block:: text
 
-       http://example.com/members/Chris/document
-       http://example.com/members/Chris/stuff/page
+   http://example.com/members/Chris/document
+   http://example.com/members/Chris/stuff/page
 
 ...wherein you'd like the ``document`` in the first URL to represent a
 PDF document, and ``/stuff/page`` in the second to represent an
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 5f9eb9140..c9929538f 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -125,7 +125,10 @@ request
 The following types work as views in this style:
 
 #. Functions that accept two arguments: ``context``, and ``request``,
-   e.g.::
+   e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -133,7 +136,10 @@ The following types work as views in this style:
           return Response('OK')
 
 #. New-style and old-style classes that have an ``__init__`` method
-   that accepts ``context, request``, e.g.::
+   that accepts ``context, request``, e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -142,7 +148,10 @@ The following types work as views in this style:
               return Response('OK')
 
 #. Arbitrary callables that have a ``__call__`` method that accepts
-   ``context, request``, e.g.::
+   ``context, request``, e.g.:
+
+   .. code-block:: python
+      :linenos:
 
       from webob import Response
 
@@ -358,7 +367,6 @@ the following:
   your application's ``configure.zcml``:
 
   .. code-block:: xml
-     :linenos:
 
       <scan package="."/>
 
@@ -366,7 +374,6 @@ the following:
   :meth:`repoze.bfg.configuration.Configurator.scan` method:
 
   .. code-block:: python
-     :linenos:
 
       config.scan()
 
@@ -436,7 +443,6 @@ Or replaces the need to add this imperative configuration stanza:
 
 .. ignore-next-block
 .. code-block:: python
-   :linenos:
 
    config.add_view(name='my_view', request_method='POST', for_=MyModel,
                    permission='read')
@@ -1461,6 +1467,7 @@ a browser client, and its ``action`` points at some :mod:`repoze.bfg`
 view code:
 
 .. code-block:: xml
+   :linenos:
 
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head>
@@ -1483,6 +1490,7 @@ expect that the values returned by ``request.params`` will be of type
 accept a form post from the above form:
 
 .. code-block:: python
+   :linenos:
 
    def myview(request):
        firstname = request.params['firstname']
@@ -1493,6 +1501,7 @@ decode already-decoded (``unicode``) values obtained from
 ``request.params``:
 
 .. code-block:: python
+   :linenos:
 
    def myview(request):
        # the .decode('utf-8') will break below if there are any high-order
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 8dbdef6f2..c4bd568c7 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -53,16 +53,16 @@ object:
     The request method, e.g., ``'GET'``, ``'POST'``
 
 ``req.GET``:
-    A `dictionary-like object`_ with all the variables in the query
+    A :term:`multidict` with all the variables in the query
     string.
 
 ``req.POST``:
-    A `dictionary-like object`_ with all the variables in the request
+    A :term:`multidict` with all the variables in the request
     body.  This only has variables if the request was a ``POST`` and
     it is a form submission.  
 
 ``req.params``:
-    A `dictionary-like object`_ with a combination of everything in
+    A :term:`multidict` with a combination of everything in
     ``req.GET`` and ``req.POST``.
 
 ``req.body``:
@@ -85,8 +85,6 @@ object:
     <http://routes.groovie.org/>`_ and `Selector
     <http://lukearno.com/projects/selector/>`_.
 
-.. _`dictionary-like object`: #multidict
-
 Also, for standard HTTP request headers there are usually attributes,
 for instance: ``req.accept_language``, ``req.content_length``,
 ``req.user_agent``, as an example.  These properties expose the
@@ -171,8 +169,8 @@ WSGI):
 
 ``response.headerlist``:
     A list of all the headers, like ``[('Content-Type',
-    'text/html')]``.  There's a case-insensitive `dictionary-like
-    object`_ in ``response.headers`` that also allows you to access
+    'text/html')]``.  There's a case-insensitive :term:`multidict`
+    in ``response.headers`` that also allows you to access
     these same headers.
 
 ``response.app_iter``:
author	Chris McDonough <chrism@agendaless.com>	2009-12-27 15:32:14 +0000
committer	Chris McDonough <chrism@agendaless.com>	2009-12-27 15:32:14 +0000
commit	e4e3aa3449d3ae390402a9cead205626816a2938 (patch)
tree	cdab3582902124055fedfb3d0320157c983638fe /docs/narr
parent	878328bdfc3b5ac832f1728e4a0461e3129cf8d4 (diff)
download	pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.tar.gz pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.tar.bz2 pyramid-e4e3aa3449d3ae390402a9cead205626816a2938.zip