grammar, caps, minor tweaks

2 files changed, 31 insertions, 27 deletions

diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index cdf52b73e..0484ebf17 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -2,25 +2,27 @@
 Basic Layout
 ============
 
-The starter files generated by the ``zodb`` scaffold are basic, but
+The starter files generated by the ``zodb`` scaffold are very basic, but
 they provide a good orientation for the high-level patterns common to most
-:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` -based) projects.
+:term:`traversal`-based (and :term:`ZODB`-based) :app:`Pyramid` projects.
 
 
-Application Configuration with ``__init__.py``
-------------------------------------------------
+Application configuration with ``__init__.py``
+----------------------------------------------
 
 A directory on disk can be turned into a Python :term:`package` by containing
 an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
-package.  Our application uses ``__init__.py`` both as a package marker and
-to contain application configuration code.
+package.  We use ``__init__.py`` both as a marker, indicating the directory
+in which it's contained is a package, and to contain application configuration
+code.
 
 When you run the application using the ``pserve`` command using the
-``development.ini`` generated config file, the application configuration
-points at a Setuptools *entry point* described as ``egg:tutorial``.  In our
-application, because the application's ``setup.py`` file says so, this entry
-point happens to be the ``main`` function within the file named
-``__init__.py``:
+``development.ini`` generated configuration file, the application
+configuration points at a Setuptools *entry point* described as
+``egg:tutorial``.  In our application, because the application's ``setup.py``
+file says so, this entry point happens to be the ``main`` function within the
+file named ``__init__.py``. Let's take a look at the code and describe what
+it does:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :linenos:
@@ -28,17 +30,19 @@ point happens to be the ``main`` function within the file named
 
 #. *Lines 1-3*.  Perform some dependency imports.
 
-#. *Lines 6-8*.  Define a root factory for our Pyramid application.
+#. *Lines 6-8*.  Define a :term:`root factory` for our Pyramid application.
 
-#. *Line 14*.  We construct a :term:`Configurator` with a :term:`root
-   factory` and the settings keywords parsed by :term:`PasteDeploy`.  The root
+#. *Line 11*.  ``__init__.py`` defines a function named ``main``.
+
+#. *Line 14*.  We construct a :term:`Configurator` with a root
+   factory and the settings keywords parsed by :term:`PasteDeploy`.  The root
    factory is named ``root_factory``.
 
 #. *Line 15*.  Include support for the :term:`Chameleon` template rendering
    bindings, allowing us to use the ``.pt`` templates.
 
-#. *Line 16*.  Register a "static view" which answers requests whose URL path
-   start with ``/static`` using the
+#. *Line 16*.  Register a "static view", which answers requests whose URL
+   paths start with ``/static``, using the
    :meth:`pyramid.config.Configurator.add_static_view` method.  This
    statement registers a view that will serve up static assets, such as CSS
    and image files, for us, in this case, at
@@ -63,7 +67,7 @@ point happens to be the ``main`` function within the file named
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
-Resources and Models with ``models.py``
+Resources and models with ``models.py``
 ---------------------------------------
 
 :app:`Pyramid` uses the word :term:`resource` to describe objects arranged
@@ -93,13 +97,12 @@ Here is the source for ``models.py``:
    root* object.  It is called on *every request* to the
    :app:`Pyramid` application.  It also performs bootstrapping by
    *creating* an application root (inside the ZODB root object) if one
-   does not already exist.  It is used by the "root_factory" we've defined
+   does not already exist.  It is used by the ``root_factory`` we've defined
    in our ``__init__.py``.
  
-   We do so by first seeing if the database has the persistent
-   application root.  If not, we make an instance, store it, and
-   commit the transaction.  We then return the application root
-   object.
+   Bootstrapping is done by first seeing if the database has the persistent
+   application root.  If not, we make an instance, store it, and commit the
+   transaction.  We then return the application root object.
 
 Views With ``views.py``
 -----------------------
@@ -171,6 +174,6 @@ opposed to the tutorial :term:`package` directory) looks like this:
 Note the existence of a ``[app:main]`` section which specifies our WSGI
 application.  Our ZODB database settings are specified as the
 ``zodbconn.uri`` setting within this section.  This value, and the other
-values within this section are passed as ``**settings`` to the ``main``
+values within this section, are passed as ``**settings`` to the ``main``
 function we defined in ``__init__.py`` when the server is started via
 ``pserve``.
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 90157aa9e..623882516 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -7,13 +7,14 @@ they provide a good orientation for the high-level patterns common to most
 :term:`URL dispatch`-based :app:`Pyramid` projects.
 
 
-Application Configuration with ``__init__.py``
+Application configuration with ``__init__.py``
 ----------------------------------------------
 
 A directory on disk can be turned into a Python :term:`package` by containing
 an ``__init__.py`` file.  Even if empty, this marks a directory as a Python
-package.  We use ``__init__.py``, both as a marker indicating the directory
-it's contained within is a package, and to contain configuration code.
+package.  We use ``__init__.py`` both as a marker, indicating the directory
+in which it's contained is a package, and to contain application configuration
+code.
 
 Open ``tutorial/tutorial/__init__.py``.  It should already contain
 the following:
@@ -136,7 +137,7 @@ Finally, ``main`` is finished configuring things, so it uses the
       :lines: 21
       :language: py
 
-View Declarations via ``views.py``
+View declarations via ``views.py``
 ----------------------------------
 
 The main function of a web framework is mapping each URL pattern to code (a