Merge pull request pypa#132 from qwcode/PEP440

PEP440 updates

Author: qwcode

source/glossary.rst

@@ -158,6 +158,16 @@ Glossary
        :ref:`pip:pip install` reference.
 
 
+    Requirement Specifier
+
+       A format used by :ref:`pip` to install packages from a :term:`Package
+       Index`. For an EBNF diagram of the format, see the
+       `pkg_resources.Requirement
+       <https://pythonhosted.org/setuptools/pkg_resources.html#requirement-objects>`_
+       entry in the :ref:`setuptools` docs. For example, "foo>=1.3" is a
+       requirement specifier, where "foo" is the project name, and the ">=1.3"
+       portion is the :term:`Version Specifier`
+
     Requirements File
 
        A file containing a list of :term:`Requirements <Requirement>` that can
@@ -191,6 +201,15 @@ Glossary
         e.g. an rpm or dpkg file.
 
 
+    Version Specifier
+
+       The version component of a :term:`Requirement Specifier`. For example,
+       the ">=1.3" portion of "foo>=1.3".  :ref:`PEP440 <pypa:PEP440s>` contains
+       a `full specification
+       <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ of the
+       specifiers that Python packaging currently supports.  Support for PEP440
+       was implemented in :ref:`setuptools` v8.0 and :ref:`pip` v6.0.
+
     Virtual Environment
 
         An isolated Python environment that allows packages to be installed for

source/installing.rst

@@ -137,14 +137,45 @@ Topics <additional>` section.
 Installing from PyPI
 ====================
 
-Install `SomeProject` and its dependencies from :term:`PyPI <Python Package
-Index (PyPI)>` using :ref:`pip:Requirement Specifiers`
+The most common usage of :ref:`pip` is to install from the :term:`Python Package
+Index <Python Package Index (PyPI)>` using a :term:`requirement specifier
+<Requirement Specifier>`. Generally speaking, a requirement specifier is
+composed of a project name followed by an optional :term:`version specifier
+<Version Specifier>`.  :ref:`PEP440 <pypa:PEP440s>` contains a `full
+specification <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_
+of the currently supported specifiers. Below are some examples.
+
+To install the latest version of "SomeProject":
 
 ::
 
- pip install SomeProject           # latest version
- pip install SomeProject==1.0.4    # specific version
- pip install 'SomeProject>=1.0.4'  # minimum version
+ pip install 'SomeProject'
+
+
+To install a specific version:
+
+::
+
+ pip install 'SomeProject==1.4'
+
+
+To install greater than or equal to one version and less than another:
+
+::
+
+ pip install 'SomeProject>=1,<2'
+
+
+To install a version that's `"compatible"
+<https://www.python.org/dev/peps/pep-0440/#compatible-release>`_ with a certain
+version: [5]_
+
+::
+
+ pip install 'SomeProject~=1.4.2'
+
+In this case, this means to install any version "==1.4.*" version that's also
+">=1.4.2".
 
 
 Upgrading packages
@@ -337,7 +368,9 @@ Install `setuptools extras`_.
        pre-installed, thereby making it an equal alternative to
        :ref:`virtualenv`.
 
-.. [5]
+.. [5] The compatible release specifier was accepted in :ref:`PEP440
+       <pypa:PEP440s>` and support was released in :ref:`setuptools` v8.0 and
+       :ref:`pip` v6.0
 
 .. _pyvenv: http://docs.python.org/3.4/library/venv.html
 .. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies