[Python-checkins] gh-101100: Documenting --prefix and --exec-prefix. (GH-102695)

[miss-islington]

https://github.com/python/cpython/commit/bef189b5c72a25a80d58c46f9e591a1b6db2187a
commit: bef189b5c72a25a80d58c46f9e591a1b6db2187a
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2023-03-15T15:14:00-07:00
summary:

gh-101100: Documenting --prefix and --exec-prefix. (GH-102695)

(cherry picked from commit 61b9ff35cbda0cc59816951a17de073968fc25c6)

Co-authored-by: Julien Palard <julien at palard.fr>
Co-authored-by: Erlend E. Aasland <erlend.aasland at protonmail.com>

files:
M Doc/c-api/init.rst
M Doc/c-api/intro.rst
M Doc/library/sys.rst
M Doc/using/configure.rst
M Doc/using/unix.rst

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index e1d2328c5f31..c453f3a14a5a 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -391,7 +391,7 @@ Process-wide parameters
    program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
    returned string points into static storage; the caller should not modify its
    value.  This corresponds to the :makevar:`prefix` variable in the top-level
-   :file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
+   :file:`Makefile` and the :option:`--prefix` argument to the :program:`configure`
    script at build time.  The value is available to Python code as ``sys.prefix``.
    It is only useful on Unix.  See also the next function.
 
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 80713c565bb8..7591537fe69f 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -78,19 +78,19 @@ used by extension writers. Structure member names do not have a reserved prefix.
 
 The header files are typically installed with Python.  On Unix, these  are
 located in the directories :file:`{prefix}/include/pythonversion/` and
-:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
-:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
+:file:`{exec_prefix}/include/pythonversion/`, where :option:`prefix <--prefix>` and
+:option:`exec_prefix <--exec-prefix>` are defined by the corresponding parameters to Python's
 :program:`configure` script and *version* is
 ``'%d.%d' % sys.version_info[:2]``.  On Windows, the headers are installed
-in :file:`{prefix}/include`, where :envvar:`prefix` is the installation
+in :file:`{prefix}/include`, where ``prefix`` is the installation
 directory specified to the installer.
 
 To include the headers, place both directories (if different) on your compiler's
 search path for includes.  Do *not* place the parent directories on the search
 path and then use ``#include <pythonX.Y/Python.h>``; this will break on
 multi-platform builds since the platform independent headers under
-:envvar:`prefix` include the platform specific headers from
-:envvar:`exec_prefix`.
+:option:`prefix <--prefix>` include the platform specific headers from
+:option:`exec_prefix <--exec-prefix>`.
 
 C++ users should note that although the API is defined entirely using C, the
 header files properly declare the entry points to be ``extern "C"``. As a result,
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 315e570416b6..cf20d33ab6e8 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1254,7 +1254,7 @@ always available.
 
    A string giving the site-specific directory prefix where the platform
    independent Python files are installed; on Unix, the default is
-   ``'/usr/local'``.  This can be set at build time with the ``--prefix``
+   :file:`/usr/local`. This can be set at build time with the :option:`--prefix`
    argument to the :program:`configure` script.  See
    :ref:`installation_paths` for derived paths.
 
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 872283615f64..ab33e0a06f51 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -120,6 +120,22 @@ General Options
 Install Options
 ---------------
 
+.. cmdoption:: --prefix=PREFIX
+
+   Install architecture-independent files in PREFIX. On Unix, it
+   defaults to :file:`/usr/local`.
+
+   This value can be retrived at runtime using :data:`sys.prefix`.
+
+   As an example, one can use ``--prefix="$HOME/.local/"`` to install
+   a Python in its home directory.
+
+.. cmdoption:: --exec-prefix=EPREFIX
+
+   Install architecture-dependent files in EPREFIX, defaults to :option:`--prefix`.
+
+   This value can be retrived at runtime using :data:`sys.exec_prefix`.
+
 .. cmdoption:: --disable-test-modules
 
    Don't build nor install test modules, like the :mod:`test` package or the
diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst
index 24c02c99f871..067ff4cce5e4 100644
--- a/Doc/using/unix.rst
+++ b/Doc/using/unix.rst
@@ -93,7 +93,7 @@ Python-related paths and files
 ==============================
 
 These are subject to difference depending on local installation conventions;
-:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
+:option:`prefix <--prefix>` and :option:`exec_prefix <--exec-prefix>`
 are installation-dependent and should be interpreted as for GNU software; they
 may be the same.