Merge pull request #910 from tshepang/venv

consistency: use $VENV whenever virtualenv binaries are used

32 files changed, 167 insertions, 158 deletions

diff --git a/HACKING.txt b/HACKING.txt
index 32381cc6c..26e85ee80 100644
--- a/HACKING.txt
+++ b/HACKING.txt
@@ -27,7 +27,7 @@ checkout.
 - Install ``setuptools-git`` into the virtualenv (for good measure, as we're
   using git to do version control)::
 
-  $ env/bin/easy_install setuptools-git
+  $ $VENV/bin/easy_install setuptools-git
 
 - Install Pyramid from the checkout into the virtualenv using ``setup.py
   dev``.  ``setup.py dev`` is an alias for "setup.py develop" which also
@@ -36,19 +36,19 @@ checkout.
   ``pyramid`` checkout directory::
 
   $ cd pyramid
-  $ ../env/bin/python setup.py dev
+  $ $VENV/bin/python setup.py dev
 
 - At that point, you should be able to create new Pyramid projects by using
   ``pcreate``::
 
   $ cd ../env
-  $ bin/pcreate -s starter starter
+  $ $VENV/bin/pcreate -s starter starter
 
 - And install those projects (also using ``setup.py develop``) into the
   virtualenv::
 
   $ cd starter
-  $ ../bin/python setup.py develop
+  $ $VENV/bin/python setup.py develop
 
 Adding Features
 ---------------
@@ -129,7 +129,7 @@ or adds the feature.
 To build and review docs (where ``$yourvenv`` refers to the virtualenv you're
 using to develop Pyramid):
 
-1. Run ``$yourvenv/bin/python setup.py dev docs``.  This will cause Sphinx
+1. Run ``$VENV/bin/python setup.py dev docs``.  This will cause Sphinx
    and all development requirements to be installed in your virtualenv.
 
 2. Update all git submodules from the top-level of your Pyramid checkout, like
@@ -139,7 +139,7 @@ using to develop Pyramid):
    HTML docs are generated.
 
 3. cd to the ``docs`` directory within your Pyramid checkout and execute
-   ``make clean html SPHINXBUILD=$yourvenv/bin/sphinx-build``.  The
+   ``make clean html SPHINXBUILD=$VENV/bin/sphinx-build``.  The
    ``SPHINXBUILD=...`` hair is there in order to tell it to use the
    virtualenv Python, which will have both Sphinx and Pyramid (for API
    documentation generation) installed.
diff --git a/docs/conventions.rst b/docs/conventions.rst
index 0c38e11d8..4cffd1084 100644
--- a/docs/conventions.rst
+++ b/docs/conventions.rst
@@ -55,21 +55,25 @@ character, e.g.:
 
   .. code-block:: text
 
-     $ ../bin/nosetests
+     $ $VENV/bin/nosetests
+
+(See :term:`virtualenv` for the meaning of ``$VENV``)
 
 Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
 drive letter and/or a directory name, e.g.:
 
   .. code-block:: text
 
-     c:\examples> ..\Scripts\nosetests
+     c:\examples> %VENV%\Scripts\nosetests
+
+(See :term:`virtualenv` for the meaning of ``%VENV%``)
 
 Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
 example block commands are prefixed only with a ``>`` character, e.g.:
 
   .. code-block:: text
 
-     > ..\Scripts\nosetests
+     > %VENV%\Scripts\nosetests
 
 When a command that should be typed on one line is too long to fit on a page,
 the backslash ``\`` is used to indicate that the following printed line
@@ -77,7 +81,7 @@ should actually be part of the command:
 
   .. code-block:: text
 
-     c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
+     c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
            --cover-erase --with-coverage
 
 A sidebar, which presents a concept tangentially related to content
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 711994426..ccff2d7db 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -150,6 +150,10 @@ Glossary
      or `the leading tool <http://www.virtualenv.org>`_ that allows one to
      create such environments.
 
+     Note: whenever you encounter commands prefixed with ``$VENV`` (Unix)
+     or ``%VENV`` (Windows), know that that is the environment variable whose
+     value is the root of the virtual environment in question.
+
    resource
      An object representing a node in the :term:`resource tree` of an
      application.  If :mod:`traversal` is used, a resource is an element in
diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst
index 3c922d0c3..07c892439 100644
--- a/docs/narr/commandline.rst
+++ b/docs/narr/commandline.rst
@@ -32,7 +32,7 @@ Here is an example for a simple view configuration using :term:`traversal`:
 .. code-block:: text
    :linenos:
 
-   $ ../bin/pviews development.ini#tutorial /FrontPage
+   $ $VENV/bin/pviews development.ini#tutorial /FrontPage
 
    URL = /FrontPage
 
@@ -56,7 +56,7 @@ A more complex configuration might generate something like this:
 .. code-block:: text
    :linenos:
 
-   $ ../bin/pviews development.ini#shootout /about
+   $ $VENV/bin/pviews development.ini#shootout /about
 
    URL = /about
 
@@ -146,7 +146,7 @@ name ``main`` as a section name:
 
 .. code-block:: text
 
-    $ bin/pshell starter/development.ini#main
+    $ $VENV/bin starter/development.ini#main
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
     [GCC 4.4.3] on linux2
     Type "help" for more information.
@@ -181,7 +181,7 @@ hash after the filename:
 
 .. code-block:: text
 
-    $ bin/pshell starter/development.ini
+    $ $VENV/bin/pshell starter/development.ini
 
 Press ``Ctrl-D`` to exit the interactive shell (or ``Ctrl-Z`` on Windows).
 
@@ -244,7 +244,7 @@ exposed, and the request is configured to generate urls from the host
 
 .. code-block:: text
 
-    $ bin/pshell starter/development.ini
+    $ $VENV/bin/pshell starter/development.ini
     Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32) 
     [GCC 4.4.3] on linux2
     Type "help" for more information.
@@ -286,7 +286,7 @@ specifically invoke one of your choice with the ``-p choice`` or
 
 .. code-block:: text
 
-   $ ../bin/pshell -p ipython | bpython | python development.ini#MyProject
+   $ $VENV/bin/pshell -p ipython | bpython | python development.ini#MyProject
 
 .. index::
    pair: routes; printing
@@ -311,7 +311,7 @@ For example:
 .. code-block:: text
    :linenos:
 
-   $ ../bin/proutes development.ini
+   $ $VENV/bin/proutes development.ini
    Name            Pattern                        View
    ----            -------                        ----                     
    home            /                              <function my_view>
@@ -354,7 +354,7 @@ configured without any explicit tweens:
 .. code-block:: text
    :linenos:
 
-   $ myenv/bin/ptweens development.ini
+   $ $VENV/bin/ptweens development.ini
    "pyramid.tweens" config value NOT set (implicitly ordered tweens used)
 
    Implicit Tween Chain
@@ -441,7 +441,7 @@ There are two required arguments to ``prequest``:
 
 For example::
 
-   $ bin/prequest development.ini /
+   $ $VENV/bin/prequest development.ini /
 
 This will print the body of the response to the console on which it was
 invoked.
@@ -452,14 +452,14 @@ config file name or URL.
 ``prequest`` has a ``-d`` (aka ``--display-headers``) option which prints the
 status and headers returned by the server before the output::
 
-   $ bin/prequest -d development.ini /
+   $ $VENV/bin/prequest -d development.ini /
 
 This will print the status, then the headers, then the body of the response
 to the console.
 
 You can add request header values by using the ``--header`` option::
 
-   $ bin/prequest --header=Host:example.com development.ini /
+   $ $VENV/bin/prequest --header=Host:example.com development.ini /
 
 Headers are added to the WSGI environment by converting them to their
 CGI/WSGI equivalents (e.g. ``Host=example.com`` will insert the ``HTTP_HOST``
@@ -472,7 +472,7 @@ using the ``-m`` (aka ``--method``) option.  ``GET``, ``HEAD``, ``POST`` and
 ``DELETE`` are currently supported.  When you use ``POST``, the standard
 input of the ``prequest`` process is used as the ``POST`` body::
 
-   $ bin/prequest -mPOST development.ini / < somefile
+   $ $VENV/bin/prequest -mPOST development.ini / < somefile
 
 .. _writing_a_script:
 
@@ -866,7 +866,7 @@ The result will be something like:
          """,
          )
 
-Once you've done this, invoking ``$somevirtualenv/bin/python setup.py
+Once you've done this, invoking ``$$VENV/bin/python setup.py
 develop`` will install a file named ``show_settings`` into the
 ``$somevirtualenv/bin`` directory with a small bit of Python code that points
 to your entry point.  It will be executable.  Running it without any
@@ -877,7 +877,7 @@ with ``foo``.  Running it with two "omit" options (e.g. ``--omit=foo
 --omit=bar``) will omit all settings that have keys that start with either
 ``foo`` or ``bar``::
 
-  $ bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar
+  $ $VENV/bin/show_settings development.ini --omit=pyramid --omit=debugtoolbar
   debug_routematch                             False               
   debug_templates                              True                
   reload_templates                             True                
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index 35bfddb8d..e059acc4e 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -546,7 +546,7 @@ for settings documented as such.  For example, you might start your
 .. code-block:: text
 
   $ PYRAMID_DEBUG_AUTHORIZATION=1 PYRAMID_RELOAD_TEMPLATES=1 \
-         bin/pserve MyProject.ini
+         $VENV/bin/pserve MyProject.ini
 
 If you started your application this way, your :app:`Pyramid`
 application would behave in the same manner as if you had placed the
diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst
index dd9281c73..beece7640 100644
--- a/docs/narr/extending.rst
+++ b/docs/narr/extending.rst
@@ -200,8 +200,8 @@ like this:
   overridden elements, such as templates and static assets as necessary.
 
 - Install the new package into the same Python environment as the original
-  application (e.g. ``$myvenv/bin/python setup.py develop`` or
-  ``$myvenv/bin/python setup.py install``).
+  application (e.g. ``$VENV/bin/python setup.py develop`` or
+  ``$VENV/bin/python setup.py install``).
 
 - Change the ``main`` function in the new package's ``__init__.py`` to include
   the original :app:`Pyramid` application's configuration functions via
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst
index ab6a46c2f..6d3786d8e 100644
--- a/docs/narr/firstapp.rst
+++ b/docs/narr/firstapp.rst
@@ -29,13 +29,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ /path/to/your/virtualenv/bin/python helloworld.py
+   $ $VENV/bin/python helloworld.py
 
 On Windows:
 
 .. code-block:: text
 
-   C:\> \path\to\your\virtualenv\Scripts\python.exe helloworld.py
+   C:\> %VENV%\Scripts\python.exe helloworld.py
 
 This command will not return and nothing will be printed to the console.
 When port 8080 is visited by a browser on the URL ``/hello/world``, the
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 24cd3ff54..74765f8e2 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -276,7 +276,7 @@ like so:
 .. code-block:: text
 
    $ cd /my/virtualenv
-   $ bin/easy_install Babel lingua
+   $ $VENV/bin/easy_install Babel lingua
 
 Installation on Windows
 +++++++++++++++++++++++
@@ -287,8 +287,7 @@ like so:
 
 .. code-block:: text
 
-   C> cd \my\virtualenv
-   C> Scripts\easy_install Babel lingua
+   C> %VENV%\Scripts\easy_install Babel lingua
 
 .. index::
    single: Babel; message extractors
@@ -347,7 +346,7 @@ extract the messages:
 
    $ cd /place/where/myapplication/setup.py/lives
    $ mkdir -p myapplication/locale
-   $ $myvenv/bin/python setup.py extract_messages
+   $ $VENV/bin/python setup.py extract_messages
 
 The message catalog ``.pot`` template will end up in:
 
@@ -439,7 +438,7 @@ init_catalog`` command:
 .. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
-   $ $myvenv/bin/python setup.py init_catalog -l es
+   $ $VENV/bin/python setup.py init_catalog -l es
 
 By default, the message catalog ``.po`` file will end up in:
 
@@ -471,7 +470,7 @@ Then use the ``setup.py update_catalog`` command.
 .. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
-   $ $myvenv/bin/python setup.py update_catalog
+   $ $VENV/bin/python setup.py update_catalog
 
 .. index::
    pair: compiling; message catalog
@@ -487,7 +486,7 @@ translations, compile ``.po`` files to ``.mo`` files:
 .. code-block:: text
 
    $ cd /place/where/myapplication/setup.py/lives
-   $ $myvenv/bin/python setup.py compile_catalog
+   $ $VENV/bin/python setup.py compile_catalog
 
 This will create a ``.mo`` file for each ``.po`` file in your
 application.  As long as the :term:`translation directory` in which
diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 85dfd5bf4..04a060ac3 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -264,16 +264,21 @@ as your system's administrative user.  For example:
 Creating the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once the :term:`virtualenv` package is installed in your Python, you
-can then create a virtual environment.  To do so, invoke the
-following:
+Once the :term:`virtualenv` package is installed in your Python environment,
+you can then create a virtual environment.  To do so, invoke the following:
 
 .. code-block:: text
 
-   $ virtualenv --no-site-packages env
-   New python executable in env/bin/python
+   $ export $VENV=~/env
+   $ virtualenv --no-site-packages $VENV
+   New python executable in /home/foo/env/bin/python
    Installing setuptools.............done.
 
+You can either follow the use of the environment variable, ``$VENV``,
+or replace it with the root directory of the :term:`virtualenv`.
+In that case, the `export` command can be skipped.
+If you choose the former approach, ensure that it's an absolute path.
+
 .. warning::
 
    Using ``--no-site-packages`` when generating your
@@ -289,20 +294,16 @@ following:
    ``virtualenv`` script.  It's perfectly acceptable (and desirable)
    to create a virtualenv as a normal user.
 
-You should perform any following commands that mention a "bin"
-directory from within the ``env`` virtualenv dir.
 
 Installing :app:`Pyramid` Into the Virtual Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After you've got your ``env`` virtualenv installed, you may install
-:app:`Pyramid` itself using the following commands from within the
-virtualenv (``env``) directory you created in the last step.
+After you've got your virtualenv installed, you may install
+:app:`Pyramid` itself using the following commands:
 
 .. code-block:: text
 
-   $ cd env
-   $ bin/easy_install pyramid
+   $ $VENV/bin/easy_install pyramid
 
 The ``easy_install`` command will take longer than the previous ones to
 complete, as it downloads and installs a number of dependencies.
@@ -339,25 +340,25 @@ Windows Using Python 2
 
       c:\> c:\Python27\python ez_setup.py
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
+#. Install `virtualenv`:
 
    .. code-block:: text
 
       c:\> c:\Python27\Scripts\easy_install virtualenv
 
-#. Use that Python's virtualenv to make a workspace:
+#. Make a :term:`virtualenv` workspace:
 
    .. code-block:: text
 
-      c:\> c:\Python27\Scripts\virtualenv --no-site-packages env
-
-#. Switch to the ``env`` directory:
-
-   .. code-block:: text
+      c:\> set VENV=c:\env
+      c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
 
-      c:\> cd env
+   You can either follow the use of the environment variable, ``%VENV%``,
+   or replace it with the root directory of the :term:`virtualenv`.
+   In that case, the `set` command can be skipped.
+   If you choose the former approach, ensure that it's an absolute path.
 
-#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
+#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
    environment wired to use the virtualenv.
 
 #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
@@ -365,7 +366,7 @@ Windows Using Python 2
 
    .. code-block:: text
 
-      c:\env> Scripts\easy_install pyramid
+      c:\env> %VENV%\Scripts\easy_install pyramid
 
 Windows Using Python 3
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -388,25 +389,25 @@ Windows Using Python 3
 
       c:\> c:\Python32\python distribute_setup.py
 
-#. Use that Python's `bin/easy_install` to install `virtualenv`:
+#. Install :term:`virtualenv`:
 
    .. code-block:: text
 
       c:\> c:\Python32\Scripts\easy_install virtualenv
 
-#. Use that Python's virtualenv to make a workspace:
+#. Make a :term:`virtualenv` workspace:
 
    .. code-block:: text
 
-      c:\> c:\Python32\Scripts\virtualenv --no-site-packages env
-
-#. Switch to the ``env`` directory:
-
-   .. code-block:: text
+      c:\> set VENV=c:\env
+      c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV%
 
-      c:\> cd env
+   You can either follow the use of the environment variable, ``%VENV%``,
+   or replace it with the root directory of the :term:`virtualenv`.
+   In that case, the `set` command can be skipped.
+   If you choose the former approach, ensure that it's an absolute path.
 
-#. (Optional) Consider using ``Scripts\activate.bat`` to make your shell
+#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell
    environment wired to use the virtualenv.
 
 #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies
@@ -414,7 +415,7 @@ Windows Using Python 3
 
    .. code-block:: text
 
-      c:\env> Scripts\easy_install pyramid
+      c:\env> %VENV%\Scripts\easy_install pyramid
 
 What Gets Installed
 -------------------
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index a9072e3bf..a168c24eb 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -80,13 +80,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ bin/pcreate -s starter MyProject
+   $ $VENV/bin/pcreate -s starter MyProject
 
 Or on Windows:
 
 .. code-block:: text
 
-   > Scripts\pcreate -s starter MyProject
+   > %VENV%\Scripts\pcreate -s starter MyProject
 
 The above command uses the ``pcreate`` command to create a project with the
 ``starter`` scaffold.  To use a different scaffold, such as
@@ -95,20 +95,20 @@ on UNIX:
 
 .. code-block:: text
 
-   $ bin/pcreate -s alchemy MyProject
+   $ $VENV/bin/pcreate -s alchemy MyProject
 
 Or on Windows:
 
 .. code-block:: text
 
-   > Scripts\pcreate -s alchemy MyProject
+   > %VENV%\Scripts\pcreate -s alchemy MyProject
 
 Here's sample output from a run of ``pcreate`` on UNIX for a project we name
 ``MyProject``:
 
 .. code-block:: text
 
-   $ bin/pcreate -s starter MyProject
+   $ $VENV/bin/pcreate -s starter MyProject
    Creating template pyramid
    Creating directory ./MyProject
    # ... more output ...
@@ -177,21 +177,21 @@ On UNIX:
 .. code-block:: text
 
    $ cd MyProject
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 Or on Windows:
 
 .. code-block:: text
 
    > cd MyProject
-   > ..\Scripts\python.exe setup.py develop
+   > %VENV%\Scripts\python.exe setup.py develop
 
 Elided output from a run of this command on UNIX is shown below:
 
 .. code-block:: text
 
    $ cd MyProject
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
    ...
    Finished processing dependencies for MyProject==0.0
 
@@ -216,19 +216,19 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 Or on Windows:
 
 .. code-block:: text
 
-   > ..\Scripts\python.exe setup.py test -q
+   > %VENV%\Scripts\python.exe setup.py test -q
 
 Here's sample output from a test run on UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
    running test
    running egg_info
    writing requirements to MyProject.egg-info/requires.txt
@@ -272,19 +272,19 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/pserve development.ini
+   $ $VENV/bin/pserve development.ini
 
 On Windows:
 
 .. code-block:: text
 
-   > ..\Scripts\pserve development.ini
+   > %VENV%\Scripts\pserve development.ini
 
 Here's sample output from a run of ``pserve`` on UNIX:
 
 .. code-block:: text
 
-   $ ../bin/pserve development.ini
+   $ $VENV/bin/pserve development.ini
    Starting server in PID 16601.
    serving on http://0.0.0.0:6543
 
@@ -359,7 +359,7 @@ For example, on UNIX:
 
 .. code-block:: text
 
-   $ ../bin/pserve development.ini --reload
+   $ $VENV/bin/pserve development.ini --reload
    Starting subprocess with file monitor
    Starting server in PID 16601.
    serving on http://0.0.0.0:6543
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 5a1a92e08..5b79edd19 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -507,7 +507,7 @@ example:
 
 .. code-block:: text
 
-  $ PYRAMID_DEBUG_AUTHORIZATION=1 bin/pserve myproject.ini
+  $ PYRAMID_DEBUG_AUTHORIZATION=1 $VENV/bin/pserve myproject.ini
 
 When any authorization takes place during a top-level view rendering,
 a message will be logged to the console (to stderr) about what ACE in
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 08fa9883e..1f1c07027 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -771,7 +771,7 @@ variable set to ``1``, For example:
 
 .. code-block:: text
 
-  $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini
+  $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini
 
 To use a setting in the application ``.ini`` file for the same
 purpose, set the ``pyramid.reload_templates`` key to ``true`` within the
diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst
index 20487b448..ca6dc565b 100644
--- a/docs/narr/upgrading.rst
+++ b/docs/narr/upgrading.rst
@@ -183,7 +183,7 @@ server run with the ``PYTHONWARNINGS`` environment variable set to
 
 .. code-block:: bash
 
-   $ PYTHONWARNINGS=default bin/pserve development.ini
+   $ PYTHONWARNINGS=default $VENV/bin/pserve development.ini
 
 On Windows, you need to issue two commands:
 
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index a327e937b..181b07259 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -875,7 +875,7 @@ which you started the application from.  For example:
 .. code-block:: text
    :linenos:
 
-    $ PYRAMID_DEBUG_ROUTEMATCH=true bin/pserve development.ini
+    $ PYRAMID_DEBUG_ROUTEMATCH=true $VENV/bin/pserve development.ini
     Starting server in PID 13586.
     serving on 0.0.0.0:6543 view at http://127.0.0.1:6543
     2010-12-16 14:45:19,956 no route matched for url \
diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst
index e68e63b0b..a50637279 100644
--- a/docs/tutorials/bfg/index.rst
+++ b/docs/tutorials/bfg/index.rst
@@ -47,7 +47,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
 
    .. code-block:: bash
 
-     $ bfgenv/bin/python setup.py test
+     $ $VENV/bin/python setup.py test
 
    ``bfgenv`` above will be the virtualenv into which you've installed
    :mod:`repoze.bfg` 1.3.
@@ -62,7 +62,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
       $ cd ~
       $ virtualenv --no-site-packages pyramidenv
       $ cd pyramidenv
-      $ bin/easy_install pyramid
+      $ $VENV/bin/easy_install pyramid
 
 #. Put a *copy* of your :mod:`repoze.bfg` application into a temporary
    location (perhaps by checking a fresh copy of the application out
@@ -186,7 +186,7 @@ Here's how to convert a :mod:`repoze.bfg` application to a
    .. code-block:: bash
 
      $ cd /tmp/bfgapp
-     $ ~/pyramidenv/bin/python setup.py test
+     $ $VENV/bin/python setup.py test
 
 #. Fix any test failures.
 
diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst
index a22f12610..e0021f8db 100644
--- a/docs/tutorials/modwsgi/index.rst
+++ b/docs/tutorials/modwsgi/index.rst
@@ -53,7 +53,7 @@ specific path information for commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/easy_install pyramid
+       $ $VENV/bin/easy_install pyramid
     
 #.  Create and install your :app:`Pyramid` application.  For the purposes of
     this tutorial, we'll just be using the ``pyramid_starter`` application as
@@ -63,9 +63,9 @@ specific path information for commands and files.
     .. code-block:: text
 
        $ cd ~/modwsgi/env
-       $ bin/pcreate -s starter myapp
+       $ $VENV/bin/pcreate -s starter myapp
        $ cd myapp
-       $ ../bin/python setup.py install
+       $ $VENV/bin/python setup.py install
 
 #.  Within the virtualenv directory (``~/modwsgi/env``), create a
     script named ``pyramid.wsgi``.  Give it these contents:
diff --git a/docs/tutorials/wiki/NOTE-relocatable.txt b/docs/tutorials/wiki/NOTE-relocatable.txt
index 4c778ad04..e942caba8 100644
--- a/docs/tutorials/wiki/NOTE-relocatable.txt
+++ b/docs/tutorials/wiki/NOTE-relocatable.txt
@@ -1,5 +1,5 @@
 We specifically use relative package references where possible so this demo
-works even if the user names their package (in the 'bin/pcreate -s
+works even if the user names their package (in the '$VENV/bin/pcreate -s
 zodb ...' step) something other than 'tutorial'.
 
 Specifically:
diff --git a/docs/tutorials/wiki/distributing.rst b/docs/tutorials/wiki/distributing.rst
index ed0af222f..9c63cf0bd 100644
--- a/docs/tutorials/wiki/distributing.rst
+++ b/docs/tutorials/wiki/distributing.rst
@@ -12,13 +12,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
diff --git a/docs/tutorials/wiki/installation.rst b/docs/tutorials/wiki/installation.rst
index b545cdba0..b51254b92 100644
--- a/docs/tutorials/wiki/installation.rst
+++ b/docs/tutorials/wiki/installation.rst
@@ -22,7 +22,7 @@ Preparation, UNIX
 
    .. code-block:: text
 
-     $ bin/easy_install docutils pyramid_tm pyramid_zodbconn \
+     $ $VENV/bin/easy_install docutils pyramid_tm pyramid_zodbconn \
                pyramid_debugtoolbar nose coverage
 
 Preparation, Windows
@@ -39,7 +39,7 @@ Preparation, Windows
 
    .. code-block:: text
 
-     c:\pyramidtut> Scripts\easy_install docutils pyramid_tm \
+     c:\pyramidtut> %VENV%\Scripts\easy_install docutils pyramid_tm \
            pyramid_zodbconn pyramid_debugtoolbar nose coverage
 
 .. _making_a_project:
@@ -59,13 +59,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ bin/pcreate -s zodb tutorial
+  $ $VENV/bin/pcreate -s zodb tutorial
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> Scripts\pcreate -s zodb tutorial
+   c:\pyramidtut> %VENV%\Scripts\pcreate -s zodb tutorial
 
 .. note:: You don't have to call it `tutorial` -- the code uses
    relative paths for imports and finding templates and static
@@ -91,14 +91,14 @@ On UNIX:
 .. code-block:: text
 
   $ cd tutorial
-  $ ../bin/python setup.py develop
+  $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
   C:\pyramidtut> cd tutorial
-  C:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+  C:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 .. _running_tests:
 
@@ -112,13 +112,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/python setup.py test -q
+  $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+  c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 Expose Test Coverage Information
 ================================
@@ -133,13 +133,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+  $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial ^
+  c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial ^
        --cover-erase --with-coverage
 
 Looks like the code in the ``zodb`` scaffold for ZODB projects is
@@ -157,13 +157,13 @@ On UNIX:
 
 .. code-block:: text
 
-  $ ../bin/pserve development.ini --reload
+  $ $VENV/bin/pserve development.ini --reload
 
 On Windows:
 
 .. code-block:: text
 
-  c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
+  c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
 .. note::
 
diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst
index 36ae7930b..e40dc286b 100644
--- a/docs/tutorials/wiki/tests.rst
+++ b/docs/tutorials/wiki/tests.rst
@@ -71,13 +71,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Once that command has completed successfully, we can run the tests
 themselves:
@@ -86,13 +86,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 The expected result looks something like:
 
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 9d2f8fb7f..5727816c8 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -52,14 +52,14 @@ On UNIX:
 .. code-block:: text
 
    $ cd tutorial
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Success executing this command will end with a line to the console something
 like::
diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst
index 96293603c..3b048a141 100644
--- a/docs/tutorials/wiki2/distributing.rst
+++ b/docs/tutorials/wiki2/distributing.rst
@@ -12,13 +12,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py sdist
+   $ $VENV/bin/python setup.py sdist
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> ..\Scripts\python setup.py sdist
+   c:\pyramidtut> %VENV%\Scripts\python setup.py sdist
 
 The output of such a command will be something like:
 
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 9fa01d513..255a60ec2 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -52,13 +52,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ bin/pcreate -s alchemy tutorial
+   $ $VENV/bin/pcreate -s alchemy tutorial
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut> Scripts\pcreate -s alchemy tutorial
+   c:\pyramidtut> %VENV%\pcreate -s alchemy tutorial
 
 .. note:: If you are using Windows, the ``alchemy``
    scaffold may not deal gracefully with installation into a
@@ -83,14 +83,14 @@ On UNIX:
 .. code-block:: text
 
    $ cd tutorial
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
    c:\pyramidtut> cd tutorial
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Success executing this command will end with a line to the console something
 like::
@@ -109,13 +109,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 For a successful test run, you should see output that ends like this::
 
@@ -141,13 +141,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/easy_install nose coverage
+   $ $VENV/bin/easy_install nose coverage
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\easy_install nose coverage
+   c:\pyramidtut\tutorial> %VENV%\Scripts\easy_install nose coverage
 
 Once ``nose`` and ``coverage`` are installed, we can actually run the
 coverage tests.
@@ -156,13 +156,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
+   $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase --with-coverage
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \
+   c:\pyramidtut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
          --cover-erase --with-coverage
 
 If successful, you will see output something like this::
@@ -200,13 +200,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/initialize_tutorial_db development.ini
+   $ $VENV/bin/initialize_tutorial_db development.ini
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\initialize_tutorial_db development.ini
+   c:\pyramidtut\tutorial> %VENV%\Scripts\initialize_tutorial_db development.ini
 
 The output to your console should be something like this::
 
@@ -248,13 +248,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/pserve development.ini --reload
+   $ $VENV/bin/pserve development.ini --reload
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\pserve development.ini --reload
+   c:\pyramidtut\tutorial> %VENV%\Scripts\pserve development.ini --reload
 
 If successful, you will see something like this on your console::
 
diff --git a/docs/tutorials/wiki2/src/authorization/README.txt b/docs/tutorials/wiki2/src/authorization/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/authorization/README.txt
+++ b/docs/tutorials/wiki2/src/authorization/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/basiclayout/README.txt b/docs/tutorials/wiki2/src/basiclayout/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/basiclayout/README.txt
+++ b/docs/tutorials/wiki2/src/basiclayout/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/models/README.txt b/docs/tutorials/wiki2/src/models/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/models/README.txt
+++ b/docs/tutorials/wiki2/src/models/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/tests/README.txt b/docs/tutorials/wiki2/src/tests/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/tests/README.txt
+++ b/docs/tutorials/wiki2/src/tests/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/src/views/README.txt b/docs/tutorials/wiki2/src/views/README.txt
index 141851285..68f430110 100644
--- a/docs/tutorials/wiki2/src/views/README.txt
+++ b/docs/tutorials/wiki2/src/views/README.txt
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_tutorial_db development.ini
+- $VENV/bin/initialize_tutorial_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini
 
diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst
index 7aa3c464d..33b5d35c1 100644
--- a/docs/tutorials/wiki2/tests.rst
+++ b/docs/tutorials/wiki2/tests.rst
@@ -66,13 +66,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py develop
+   $ $VENV/bin/python setup.py develop
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py develop
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
 Once that command has completed successfully, we can run the tests
 themselves:
@@ -81,13 +81,13 @@ On UNIX:
 
 .. code-block:: text
 
-   $ ../bin/python setup.py test -q
+   $ $VENV/bin/python setup.py test -q
 
 On Windows:
 
 .. code-block:: text
 
-   c:\pyramidtut\tutorial> ..\Scripts\python setup.py test -q
+   c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py test -q
 
 The expected result ends something like:
 
diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst
index 18d0aa0b1..f33fc94ba 100644
--- a/docs/whatsnew-1.1.rst
+++ b/docs/whatsnew-1.1.rst
@@ -395,8 +395,9 @@ Deprecations and Behavior Differences
    when porting your application from an older version of Pyramid.  Use the
    ``PYTHONWARNINGS`` environment variable with the value ``all`` in the
    shell you use to invoke ``paster serve`` to see these warnings, e.g. on
-   UNIX, ``PYTHONWARNINGS=all bin/paster serve development.ini``.  Python 2.5
-   and 2.6 show deprecation warnings by default, so this is unecessary there.
+   UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``.
+   Python 2.5 and 2.6 show deprecation warnings by default,
+   so this is unecessary there.
    All deprecation warnings are emitted to the console.
 
 - The :class:`pyramid.view.static` class has been deprecated in favor of the
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index d121413e2..ef0256383 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -46,12 +46,12 @@ maintain them ourselves.  As a result, we've had to make some changes.
 Previously (in Pyramid 1.0, 1.1 and 1.2), you created a Pyramid application
 using ``paster create``, like so::
 
-    $ myvenv/bin/paster create -t pyramid_starter foo
+    $ $VENV/bin/paster create -t pyramid_starter foo
 
 In 1.3, you're now instead required to create an application using
 ``pcreate`` like so::
 
-    $ myvenv/bin/pcreate -s starter foo
+    $ $VENV/bin/pcreate -s starter foo
 
 ``pcreate`` is required to be used for internal Pyramid scaffolding;
 externally distributed scaffolding may allow for both ``pcreate`` and/or
@@ -59,11 +59,11 @@ externally distributed scaffolding may allow for both ``pcreate`` and/or
 
 In previous Pyramid versions, you ran a Pyramid application like so::
 
-    $ myvenv/bin/paster serve development.ini
+    $ $VENV/bin/paster serve development.ini
 
 Instead, you now must use the ``pserve`` command in 1.3::
 
-    $ myvenv/bin/pserve development.ini
+    $ $VENV/bin/pserve development.ini
 
 The ``ini`` configuration file format supported by Pyramid has not changed.
 As a result, Python 2-only users can install PasteScript manually and use
diff --git a/pyramid/scaffolds/alchemy/README.txt_tmpl b/pyramid/scaffolds/alchemy/README.txt_tmpl
index 9e4aa1125..a05c0e174 100644
--- a/pyramid/scaffolds/alchemy/README.txt_tmpl
+++ b/pyramid/scaffolds/alchemy/README.txt_tmpl
@@ -6,9 +6,9 @@ Getting Started
 
 - cd <directory containing this file>
 
-- $venv/bin/python setup.py develop
+- $VENV/bin/python setup.py develop
 
-- $venv/bin/initialize_{{project}}_db development.ini
+- $VENV/bin/initialize_{{project}}_db development.ini
 
-- $venv/bin/pserve development.ini
+- $VENV/bin/pserve development.ini