README.md: Expand section 'Alternative Installation using PyPI'

Author: Matthias Koeppe

README.md

@@ -420,16 +420,47 @@ in the Installation Guide.
 Alternative Installation using PyPI
 ---------------
 
-For installation of `sage` in python using `pip` you need to install `sagemath-standard`. First, activate your python virtual environment and follow these steps:
+For installing Sage in a Python environment from PyPI, Sage provides the
+`pip`-installable package [sagemath-standard](https://pypi.org/project/sagemath-standard/).
 
-            $ python3 -m pip install sage_conf
-            $ ls $(sage-config SAGE_SPKG_WHEELS)
-            $ python3 -m pip install $(sage-config SAGE_SPKG_WHEELS)/*.whl sage_setup
-            $ python3 -m pip install --no-build-isolation sagemath-standard
+Unless you need to install Sage into a specific existing environment, we recommend
+to create and activate a fresh virtual environment, for example `~/sage-venv/`:
 
-You need to install `sage_conf`, a wheelhouse of various python packages. You can list the wheels using `ls $(sage-config SAGE_SPKG_WHEELS)`. After manual installation of these wheels, you can install the sage library, `sagemath-standard`.
+            $ python3 -m venv ~/sage-venv
+            $ source ~/sage-venv/bin/activate
 
-**NOTE:** You can find `sage` and `sagemath` pip packages but with these packages, you will encounter `ModuleNotFoundError`.
+As the first installation step, install [sage_conf](https://pypi.org/project/sage-conf/),
+which builds various prerequisite packages in a subdirectory of `~/.sage/`:
+
+            (sage-venv) $ python3 -m pip install -v sage_conf
+
+After a successful installation, a wheelhouse provides various Python packages.
+You can list the wheels using the command:
+
+            (sage-venv) $ ls $(sage-config SAGE_SPKG_WHEELS)
+
+If this gives an error saying that `sage-config` is not found, check any messages
+that the `pip install` command may have printed. You may need to adjust your `PATH`,
+for example by:
+
+            $ export PATH="$(python3 -c 'import sysconfig; print(sysconfig.get_path("scripts", "posix_user"))'):$PATH"
+
+Now install the packages from the wheelhouse and the [sage_setup](https://pypi.org/project/sage-conf/)
+package, and finally install the Sage library:
+
+            (sage-venv) $ python3 -m pip install $(sage-config SAGE_SPKG_WHEELS)/*.whl sage_setup
+            (sage-venv) $ python3 -m pip install --no-build-isolation -v sagemath-standard
+
+The above instructions install the latest stable release of Sage.
+To install the latest development version instead, add the switch `--pre` to all invocations of
+`python3 -m pip install`.
+
+**NOTE:** PyPI has various other `pip`-installable packages with the word "sage" in their names.
+Some of them are maintained by the SageMath project, some are provided by SageMath users for
+various purposes, and others are entirely unrelated to SageMath. Do not use the packages
+`sage` and `sagemath`. For a curated list of packages, see the chapter
+[Packages and Features](https://doc.sagemath.org/html/en/reference/spkg/index.html) of the
+Sage Reference Manual.
 
 SageMath Docker images
 ----------------------