From 21f2b61272f83de110087344e68f32953cd7b42f Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Sat, 24 Sep 2016 20:39:45 -0700
Subject: Why use venv/bin/pip instead of source bin/activate then pip? -
 Closes #2610

---
 docs/narr/install.rst                | 21 +++++++++++++++++++++
 docs/quick_tour.rst                  |  4 +++-
 docs/quick_tutorial/requirements.rst |  3 +++
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 677c27e4a..7b5d8361b 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -191,6 +191,24 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
 
       $ $VENV/bin/pip install "pyramid==\ |release|\ "
 
+.. index::
+   single: $VENV/bin/pip vs. source bin/activate
+
+.. _venv-bin-pip-vs-source-bin-activate:
+
+.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
+   ``pip``?
+
+   Although the latter method requires fewer key strokes to issue commands once
+   invoked, there are numerous reasons why one should avoid using ``activate``
+   within a virtual environment. Michael F. Lamb (datagrok) presents a summary
+   in `Virtualenv's bin/activate is Doing It Wrong
+   <https://gist.github.com/datagrok/2199506>`_, and proposes alternatives,
+   followed by comments from other developers.
+
+   However, we prefer to keep things simple. ``$VENV/bin/pip`` is already
+   UNIX-y. The few extra key strokes are worth avoiding the mess altogether.
+
 
 .. index::
    single: installing on Windows
@@ -227,6 +245,9 @@ After installing Python as described previously in
 
       c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ "
 
+.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
+
 
 What Gets Installed
 -------------------
diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst
index b2dec77e9..39b4cafb3 100644
--- a/docs/quick_tour.rst
+++ b/docs/quick_tour.rst
@@ -59,7 +59,9 @@ show only UNIX commands.
 
 .. seealso:: See also:
     :ref:`Quick Tutorial section on Requirements <qtut_requirements>`,
-    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and
+    :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`,
+    :ref:`Why use $VENV/bin/pip instead of source bin/activate, then pip
+    <venv-bin-pip-vs-source-bin-activate>`, and
     :ref:`Installing Pyramid on a Windows System <installing_windows>`.
 
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 1de9a8acf..afa8ed104 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -179,6 +179,9 @@ time of its release.
     # Windows
     c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
 
+.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
+   bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
+
 
 .. _install-pyramid:
 
-- 
cgit v1.2.3