consistency: use $VENV whenever virtualenv binaries are used

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.

docs/conventions.rst

@@ -55,29 +55,33 @@ 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
 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

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

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                

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

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

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

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