Address Victor's review

Author: erlend-aasland

Doc/howto/perf_profiling.rst

@@ -102,7 +102,7 @@ As you can see here, the Python functions are not shown in the output, only ``_P
 functions use the same C function to evaluate bytecode so we cannot know which Python function corresponds to which
 bytecode-evaluating function.
 
-Instead, if we run the same experiment with ``perf`` support activated we get:
+Instead, if we run the same experiment with ``perf`` support enabled we get:
 
 .. code-block:: shell-session
 
@@ -148,10 +148,10 @@ Instead, if we run the same experiment with ``perf`` support activated we get:
 
 
 
-How to enable the ``perf`` profiling mode
------------------------------------------
+How to enable ``perf`` profiling support
+----------------------------------------
 
-There are three ways to activate the ``perf`` profiling mode:
+There are three ways to enable ``perf`` profiling support:
 
 * using the :option:`-Xperf <-X>` command-line option
 * using the :envvar:`PYTHONPERFSUPPORT` environment variable
@@ -163,11 +163,11 @@ use the :option:`-Xperf <-X>` option::
 
     $ python -Xperf my_script.py
 
-If you need to activate the ``perf`` profiling mode globally,
+If you need to enable ``perf`` profiling support globally,
 set the environment variable :envvar:`PYTHONPERFSUPPORT`
 to a nonzero value.
 
-If you need to dynamically activate and deactivate the ``perf`` profiling mode
+If you need to dynamically enable and disable ``perf`` profiling
 in response to a signal or other communication mechanisms with your process,
 use the :func:`sys.activate_stack_trampoline` and
 :func:`sys.deactivate_stack_trampoline` APIs:

Doc/using/cmdline.rst

@@ -535,13 +535,11 @@ Miscellaneous options
      development (running from the source tree) then the default is "off".
      Note that the "importlib_bootstrap" and "importlib_bootstrap_external"
      frozen modules are always used, even if this flag is set to "off".
-   * ``-X perf`` activates compatibility mode with the ``perf`` profiler.
-     When this option is activated, the Linux ``perf`` profiler will be able to
+   * ``-X perf`` enables support for the Linux ``perf`` profiler.
+     When this option is provided, the ``perf`` profiler will be able to
      report Python calls. This option is only available on some platforms and
      will do nothing if is not supported on the current system. The default value
-     is "off". See :ref:`perf_profiling` for more details.
-     This option is equivalent to setting the environment variable
-     :envvar:`PYTHONPERFSUPPORT` to ``1``.
+     is "off". See also :envvar:`PYTHONPERFSUPPORT` and :ref:`perf_profiling`.
 
    It also allows passing arbitrary values and retrieving them through the
    :data:`sys._xoptions` dictionary.
@@ -1036,14 +1034,13 @@ conflict.
 
 .. envvar:: PYTHONPERFSUPPORT
 
-   If this variable is set to a nonzero value, it activates compatibility mode
-   with the ``perf`` profiler so Python calls can be detected by it.
-   This is exactly equivalent to setting :option:`-X perf <-X>`
-   on the command line.
+   If this variable is set to a nonzero value, it enables support for
+   the Linux ``perf`` profiler so Python calls can be detected by it.
 
-   If set to ``0``, disable ``perf`` profiler support.
+   If set to ``0``, disable Linux ``perf`` profiler support.
 
-   See :ref:`perf_profiling` for more details.
+   See also the :option:`-X perf <-X>` command-line option
+   and :ref:`perf_profiling`.
 
    .. versionadded:: 3.12