From 657d91f6725336718a42b6661d728f54afaa1498 Mon Sep 17 00:00:00 2001
From: Tzu-ping Chung <uranusjr@gmail.com>
Date: Sat, 14 Nov 2020 03:56:01 +0800
Subject: [PATCH] Reorder and revise installation docs

An additional section is added to instruct the user to self-check
whether pip is installed before proceeding.

The Linux package manager section is moved to the front to encourage
users to try that first before learning about get-pip.py, which tends to
provide seemingly working but subtly broken results there. A paragraph
is added to the section to instruct users to report issues to package
managers instead.

A new section on enturepip is added as an alternative to get-pip.py,
which is almost guarenteed to be available at this point.
---
 docs/html/installing.rst | 76 +++++++++++++++++++++++++++++++---------
 news/9131.doc.rst        |  1 +
 2 files changed, 60 insertions(+), 17 deletions(-)
 create mode 100644 news/9131.doc.rst

diff --git a/docs/html/installing.rst b/docs/html/installing.rst
index 00c74a70a..a49aebea4 100644
--- a/docs/html/installing.rst
+++ b/docs/html/installing.rst
@@ -10,8 +10,58 @@ Do I need to install pip?
 pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4
 downloaded from `python.org <https://www.python.org>`_ or if you are working
 in a :ref:`Virtual Environment <pypug:Creating and using Virtual Environments>`
-created by :ref:`pypug:virtualenv` or :ref:`pyvenv <pypug:venv>`.
-Just make sure to :ref:`upgrade pip <Upgrading pip>`.
+created by :ref:`pypug:virtualenv` or :ref:`venv <pypug:venv>`. Just make sure
+to :ref:`upgrade pip <Upgrading pip>`.
+
+Use the following command to check whether pip is installed:
+
+.. tab:: Unix/macOS
+
+   .. code-block:: console
+
+      $ python -m pip --version
+      pip X.Y.Z from .../site-packages/pip (python X.Y)
+
+.. tab:: Windows
+
+   .. code-block:: console
+
+      C:\> py -m pip --version
+      pip X.Y.Z from ...\site-packages\pip (python X.Y)
+
+Using Linux Package Managers
+============================
+
+.. warning::
+
+   If you installed Python from a package manager on Linux, you should always
+   install pip for that Python installation using the same source.
+
+See `pypug:Installing pip/setuptools/wheel with Linux Package Managers <https://packaging.python.org/guides/installing-using-linux-tools/>`_
+in the Python Packaging User Guide.
+
+Here are ways to contact a few Linux package maintainers if you run into
+problems:
+
+* `Deadsnakes PPA <https://github.com/deadsnakes/issues>`_
+* `Debian Python Team <https://wiki.debian.org/Teams/PythonTeam>`_ (for general
+  issues related to ``apt``)
+* `Red Hat Bugzilla <https://bugzilla.redhat.com/>`_
+
+pip developers do not have control over how Linux distributions handle pip
+installations, and are unable to provide solutions to related issues in
+general.
+
+Using ensurepip
+===============
+
+Python >=3.4 can self-bootstrap pip with the built-in
+:ref:`ensurepip <pypug:ensurepip>` module. Refer to the standard library
+documentation for more details. Make sure to :ref:`upgrade pip <Upgrading pip>`
+after ``ensurepip`` installs pip.
+
+See the `Using Linux Package Managers`_ section if your Python reports
+``No module named ensurepip`` on Debian and derived systems (e.g. Ubuntu).
 
 
 .. _`get-pip`:
@@ -19,7 +69,13 @@ Just make sure to :ref:`upgrade pip <Upgrading pip>`.
 Installing with get-pip.py
 ==========================
 
-To install pip, securely [1]_ download ``get-pip.py`` by following
+.. warning::
+
+   Be cautious if you are using a Python install that is managed by your operating
+   system or another package manager. ``get-pip.py`` does not coordinate with
+   those tools, and may leave your system in an inconsistent state.
+
+To manually install pip, securely [1]_ download ``get-pip.py`` by following
 this link: `get-pip.py
 <https://bootstrap.pypa.io/get-pip.py>`_. Alternatively, use ``curl``::
 
@@ -40,13 +96,6 @@ have downloaded ``get-pip.py``:
 
       py get-pip.py
 
-
-.. warning::
-
-   Be cautious if you are using a Python install that is managed by your operating
-   system or another package manager. ``get-pip.py`` does not coordinate with
-   those tools, and may leave your system in an inconsistent state.
-
 ``get-pip.py`` also installs :ref:`pypug:setuptools` [2]_ and :ref:`pypug:wheel`
 if they are not already. :ref:`pypug:setuptools` is required to install
 :term:`source distributions <pypug:Source Distribution (or "sdist")>`.  Both are
@@ -134,13 +183,6 @@ Install behind a proxy:
 
       py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0
 
-Using Linux Package Managers
-============================
-
-See :ref:`pypug:Installing pip/setuptools/wheel with Linux Package Managers` in
-the `Python Packaging User Guide
-<https://packaging.python.org/guides/tool-recommendations/>`_.
-
 .. _`Upgrading pip`:
 
 Upgrading pip
diff --git a/news/9131.doc.rst b/news/9131.doc.rst
new file mode 100644
index 000000000..18862aa55
--- /dev/null
+++ b/news/9131.doc.rst
@@ -0,0 +1 @@
+Reorder and revise installation instructions to make them easier to follow.