General cleanup.

4 files changed, 31 insertions, 20 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 81294e896..e70ffc1d3 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -9,9 +9,9 @@ Before You Install
 You will need `Python <http://python.org>`_ version 2.4 or better to
 run :mod:`repoze.bfg`.  It has been tested under Python 2.4.5, Python
 2.5.2 and Python 2.6.  Development of :mod:`repoze.bfg` is currently
-done primarily under Python 2.4.  :mod:`repoze.bfg` does *not* run
-under any version of Python before 2.4, and does *not* run under
-Python 3.X.
+done primarily under Python 2.4 and Python 2.5.  :mod:`repoze.bfg`
+does *not* run under any version of Python before 2.4, and does *not*
+run under Python 3.X.
 
 .. note:: You will need :term:`setuptools` installed
    on within your Python system in order to run the ``easy_install``
@@ -21,21 +21,29 @@ Python 3.X.
    not require the compilation of any C code, so you do not need to
    have development tools installed on the target machine.
 
-Although BFG is known to run properly on all Unix-like systems, at the
-time of this writing, ``repoze.bfg`` is not tested on Windows systems.
-It might run; it might not.  There's nothing intrinsic about
-:mod:`repoze.bfg` that would prevent it from running on Windows, but
-none of the current developers use the platform.  Likewise for
-platforms like Jython, and Google App Engine; it may run, it may not.
+BFG is known to run properly on all popular (and even some
+less-popular) Unix-like systems such as Linux, MacOS X, and FreeBSD.
+
+At the time of this writing, ``repoze.bfg`` will run on Windows
+systems.  However, none of its developers use the Windows platform, so
+it is not tested regularly on Windows.  Most of the platform-specific
+documentation (including this chapter) assumes you're installing it on
+a UNIX system.
+
+:mod:`repoze.bfg` is known to run on Google's App Engine.  See
+:ref:`appengine_tutorial`.
+
+It is not known whether :mod:`repoze.bfg` will or will not run under
+Jython or IronPython.
 
 .. note:: If you'd like to help make sure :mod:`repoze.bfg` keeps
-.. running on your favorite alternate platform, we'd love to hear from
+   running on your favorite alternate platform, we'd love to hear from
    you.  Please contact us via the `repoze.dev maillist
    <http://lists.repoze.org/listinfo/repoze-dev>`_ if you'd like to
    contribute.
 
-Installing :mod:`repoze.bfg`
-----------------------------
+Installing :mod:`repoze.bfg` on a UNIX System
+---------------------------------------------
 
 It is advisable to install :mod:`repoze.bfg` into a :term:`virtualenv`
 in order to obtain isolation from any "system" packages you've got
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index c43f1f77e..5b15e9f44 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -92,9 +92,10 @@ application's Python code and templates.
    <http://www.sqlalchemy.org/>`_ also exist.  Use ``paster create -t
    bfg_zodb`` to create a project that depends on ZODB.  Use ``paster
    create -t bfg_routesalchemy`` to create a project that depends on
-   SQLAlchemy+Routes.  Use ``paster create -t bfg_alchemy`` to create
-   a project that depends on SQLAlchemy but not Routes (uses traversal
-   instead of URL dispatch).
+   SQLAlchemy and Routes (uses :term:`URL dispatch` instead of
+   :term:`traversal`).  Use ``paster create -t bfg_alchemy`` to create
+   a project that depends on SQLAlchemy but *not* Routes (uses
+   :term:`traversal` instead of :term:`URL dispatch`).
 
 Installing your Newly Created Project for Development
 -----------------------------------------------------
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index d4c77288b..748800235 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -62,10 +62,10 @@ When a user requests a page from your :mod:`repoze.bfg` -powered
 application, the system uses this algorithm to determine which Python
 code to execute:
 
-#.  The request for the page is presented to :mod:`repoze.bfg`'s
-     "router" in terms of a standard :term:`WSGI` request, which is
-     represented by a WSGI environment and a ``start_response``
-     callable.
+#.  The request for the page is presented to the :mod:`repoze.bfg`
+    "router" in terms of a standard :term:`WSGI` request, which is
+    represented by a WSGI environment and a ``start_response``
+    callable.
 
 #.  The router creates a :term:`WebOb` request object based on the
     WSGI environment.
@@ -246,7 +246,7 @@ Let's say that question is answered "here you go, here'a a bit of code
 that is willing to deal with that case", and returns a :term:`view`.
 It is passed the "biz" object as the "context" and the current
 :term:`WebOb` :term:`request` as the "request".  It returns a
-term:`response`.
+:term:`response`.
 
 There are two special cases:
 
diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst
index 07aa7ccf4..18a2f0da4 100644
--- a/docs/tutorials/gae/index.rst
+++ b/docs/tutorials/gae/index.rst
@@ -1,3 +1,5 @@
+.. _appengine_tutorial:
+
 Running :mod:`repoze.bfg` on Google's App Engine
 ================================================