Add documentation for PEP 370 features in distutils (#10745).

Apart from adding a section to describe the user scheme, this changeset
also does some much needed cleanup:

- fixed inverted reST targets
- fixed some paths
- avoided duplicating the same options listing five or six times
- added missing entries for C headers locations
- added documentation for --install-lib
- fixed a few misuses of the option role (see #9312), but not all (not
  worth the time, but will do it in packaging docs)
- fixed some markup

The paths fixes were done with an eye on the source code in the install
command, so they really describe what’s actually done.  The situation on
Mac OS X is rather messy: the fix for #8084 touched site and sysconfig,
but distutils does not use these files anymore since the Great Revert.
I suspect we have a mismatched stdlib at the moment, and the fix is not
even clear (see discussion on #8084).

Doc/library/site.rst

@@ -138,14 +138,16 @@ empty, and the path manipulations are skipped; however the import of
    :file:`~/Library/Python/{X.Y}` for Mac framework builds, and
    :file:`{%APPDATA%}\\Python` for Windows.  This value is used by Distutils to
    compute the installation directories for scripts, data files, Python modules,
-   etc.  See also :envvar:`PYTHONUSERBASE`.
+   etc. for the :ref:`user installation scheme <inst-alt-install-user>`.  See
+   also :envvar:`PYTHONUSERBASE`.
 
    .. versionadded:: 2.6
 
 
 .. function:: addsitedir(sitedir, known_paths=None)
 
-   Add a directory to sys.path and process its :file:`.pth` files.
+   Add a directory to sys.path and process its :file:`.pth` files.  Typically
+   used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
 
 
 .. function:: getsitepackages()

Doc/using/cmdline.rst

@@ -547,7 +547,8 @@ These environment variables influence Python's behavior.
 
    Defines the :data:`user base directory <site.USER_BASE>`, which is used to
    compute the path of the :data:`user site-packages directory <site.USER_SITE>`
-   and Distutils installation paths for ``python setup.py install --user``.
+   and :ref:`Distutils installation paths <inst-alt-install-user>` for ``python
+   setup.py install --user``.
 
    .. versionadded:: 2.6