Apply suggestions from code review

Co-authored-by: Mark Shannon <Mark.Shannon@arm.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Author: 3 people

peps/pep-0831.rst

@@ -29,7 +29,7 @@ This PEP proposes two things:
    with frame pointers by default.**  This PEP recommends that *every* compiled
    component that participates in the Python call stack (C extensions, Rust
    extensions, embedding applications, and native libraries) should enable
-   frame pointers.  A frame-pointer chain is only as complete as its weakest
+   frame pointers.  A frame-pointer chain is only as strong as its weakest
    link: a single library without frame pointers breaks profiling, debugging,
    and tracing for the entire process.
 
@@ -101,8 +101,8 @@ the entire call stack::
 Stack unwinding is the process of walking this chain to reconstruct the call
 stack.  Profilers do it to find out where the program is spending time;
 debuggers do it to show backtraces; crash handlers do it to produce useful
-error reports.  With frame pointers, unwinding is a simple pointer chase: read
-``%rbp``, follow the link, repeat. It takes microseconds and requires no
+error reports.  With frame pointers, unwinding is a simply following pointers: read
+``%rbp``, follow the link, repeat. It is very fast and requires no
 external data.
 
 At optimisation levels ``-O1`` and above, GCC and Clang omit frame pointers by
@@ -322,15 +322,14 @@ BPF programs for production monitoring), frame pointers are the only viable
 unwinding mechanism because they are the only mechanism the kernel's built-in
 helpers support.
 
-CPython's own documentation already states the recommended fix::
+:ref:`CPython's own documentation <python:perf_profiling>`__ already states the
+recommended fix:
 
     For best results, Python should be compiled with
-    CFLAGS='-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer'
+    ``CFLAGS="-fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"``
     as this allows profilers to unwind using only the frame pointer
     and not on DWARF debug information.
 
-    -- docs.python.org/3/howto/perf_profiling.html
-
 Production profiling tools echo this guidance.  Grafana Pyroscope's
 troubleshooting documentation states: "If your profiles show many shallow stack
 traces, typically 1-2 frames deep, your binary might have been compiled without
@@ -359,16 +358,14 @@ Distributions Are Waiting for Upstream
 
 Fedora 38 [#fedora38]_, Ubuntu 24.04 LTS [#ubuntu2404]_, and Arch Linux have
 all rebuilt their entire package trees with ``-fno-omit-frame-pointer
--mno-omit-leaf-frame-pointer``.  However, Ubuntu 24.04 LTS explicitly exempted
-CPython::
+-mno-omit-leaf-frame-pointer``.  However, Ubuntu 24.04 LTS
+`explicitly exempted CPython
+<https://ubuntu.com/blog/ubuntu-performance-engineering-with-frame-pointers-by-default>`__:
 
     In cases where the impact is high (such as the Python
     interpreter), we'll continue to omit frame pointers until
     this is addressed.
 
-    -- ubuntu.com/blog/ubuntu-performance-engineering-with-
-       frame-pointers-by-default
-
 The result is a circular dependency: the runtime most in need of frame pointers
 for profiling is the one that major distributions leave without them, pending
 an upstream fix.  Red Hat Enterprise Linux and CentOS Stream also disable frame
@@ -395,7 +392,7 @@ The need for a continuous chain is precisely why the flags must propagate to
 extension builds. If only the interpreter has frame pointers but extensions do
 not, the chain is still broken at every C extension boundary.  By adding the
 flags to ``CFLAGS`` as reported by ``sysconfig``, extension builds that consume
-CPython's compiler flags (for example via ``pip install``, ``setuptools``, or
+CPython's compiler flags (for example via ``pip install``, Setuptools, or
 ``python setup.py build``) will inherit frame pointers by default.  Extensions
 and libraries with independent build systems still need to enable the same
 flags themselves for the frame-pointer chain to remain continuous.
@@ -517,7 +514,7 @@ Ecosystem Impact
 
 Because the flags are in ``CFLAGS``, they propagate automatically to consumers
 that build against CPython's reported compiler flags, such as C extensions
-built via ``pip``, ``setuptools``, or direct ``sysconfig`` queries.  Those
+built via pip, Setuptools, or direct ``sysconfig`` queries.  Those
 consumers need take no additional action to benefit from this change.
 
 Not all compiled code in the Python ecosystem inherits CPython's ``CFLAGS``.