python
diff --git a/‎pep-0558.rst
Lines changed: 56 additions & 52 deletions b/‎pep-0558.rst
Lines changed: 56 additions & 52 deletions
@@ -24,7 +24,9 @@ behaviour at function scope to make it more predictable and independent of the
 presence or absence of tracing functions.
 
 In addition, it proposes that the following functions be added to the stable
-Python C API/ABI::
+Python C API/ABI:
+
+.. code-block:: c
 
     typedef enum {
       PyLocals_UNDEFINED = -1,
@@ -145,7 +147,7 @@ builtin to read as follows:
     dictionaries.
 
 
-There would also be a versionchanged note for the release making this change:
+There would also be a ``versionchanged`` note for the release making this change:
 
     In prior versions, the semantics of mutating the mapping object returned
     from ``locals()`` were formally undefined. In CPython specifically,
@@ -273,14 +275,20 @@ Summary of proposed implementation-specific changes
 
 * Changes are made as necessary to provide the updated Python level semantics
 * Two new functions are added to the stable ABI to replicate the updated
-  behaviour of the Python ``locals()`` builtin::
+  behaviour of the Python ``locals()`` builtin:
+
+.. code-block:: c
 
      PyObject * PyLocals_Get();
      PyLocals_Kind PyLocals_GetKind();
+
 * One new function is added to the stable ABI to efficiently get a snapshot of
-  the local namespace in the running frame::
+  the local namespace in the running frame:
+
+.. code-block:: c
 
      PyObject * PyLocals_GetCopy();
+
 * Corresponding frame accessor functions for these new public APIs are added to
   the CPython frame C API
 * On optimised frames, the Python level ``f_locals`` API will return dynamically
@@ -494,7 +502,9 @@ independent, behaviour. However, it is also desirable to allow C code to
 exactly mimic the behaviour of Python code at the same scope.
 
 To enable mimicking the behaviour of Python code, the stable C ABI would gain
-the following new functions::
+the following new functions:
+
+.. code-block:: c
 
     PyObject * PyLocals_Get();
     PyLocals_Kind PyLocals_GetKind();
@@ -526,15 +536,19 @@ information visually through lexical scoping (as covered in the new ``locals()``
 builtin documentation).
 
 To allow extension module code to behave consistently regardless of the active
-Python scope, the stable C ABI would gain the following new function::
+Python scope, the stable C ABI would gain the following new function:
+
+.. code-block:: c
 
     PyObject * PyLocals_GetCopy();
 
 ``PyLocals_GetCopy()`` returns a new dict instance populated from the current
 locals namespace. Roughly equivalent to ``dict(locals())`` in Python code, but
 avoids the double-copy in the case where ``locals()`` already returns a shallow
 copy. Akin to the following code, but doesn't assume there will only ever be
-two kinds of locals result::
+two kinds of locals result:
+
+.. code-block:: c
 
     locals = PyLocals_Get();
     if (PyLocals_GetKind() == PyLocals_DIRECT_REFERENCE) {
@@ -598,7 +612,9 @@ specifics of when the namespace it returns gets refreshed are still an
 interpreter implementation detail)
 
 The additions to the public CPython C API are the frame level enhancements
-needed to support the stable C API/ABI updates::
+needed to support the stable C API/ABI updates:
+
+.. code-block:: c
 
     PyLocals_Kind PyFrame_GetLocalsKind(frame);
     PyObject * PyFrame_GetLocals(frame);
@@ -628,7 +644,9 @@ affected code should be updated to use
 instead.
 
 In addition to the above documented interfaces, the draft reference
-implementation also exposes the following undocumented interfaces::
+implementation also exposes the following undocumented interfaces:
+
+.. code-block:: c
 
     PyTypeObject _PyFastLocalsProxy_Type;
     #define _PyFastLocalsProxy_CheckExact(self) Py_IS_TYPE(op, &_PyFastLocalsProxy_Type)
@@ -1016,7 +1034,7 @@ specifically related to the C API:
 * :pep:`667` still proposes completely unnecessary C API breakage (the programmatic
   deprecation and eventual removal of ``PyEval_GetLocals()``,
   ``PyFrame_FastToLocalsWithError()``, and ``PyFrame_FastToLocals()``) without
-  justification, when it is entirely possible to keep these working indefintely
+  justification, when it is entirely possible to keep these working indefinitely
   (and interoperably) given a suitably designed fast locals proxy implementation
 * the fast locals proxy handling of additional variables is defined in this PEP
   in a way that is fully interoperable with the existing ``PyEval_GetLocals()``
@@ -1029,7 +1047,7 @@ specifically related to the C API:
   like a type name than a data access API.
 * this PEP adds ``PyLocals_GetCopy()`` and ``PyFrame_GetLocalsCopy()`` APIs to
   allow extension modules to easily avoid incurring a double copy operation in
-  frames where ``PyLocals_Get()`` alreadys makes a copy
+  frames where ``PyLocals_Get()`` already makes a copy
 * this PEP adds ``PyLocals_Kind``, ``PyLocals_GetKind()``, and
   ``PyFrame_GetLocalsKind()`` to allow extension modules to identify when code
   is running at function scope without having to inspect non-portable frame and
@@ -1238,7 +1256,7 @@ complexity improvement.
 The O(1) nature of the other operations can be restored by adding implementation
 code that doesn't rely on the value cache being up to date.
 
-Keeping the iterator/iterable retrieval methods as ``O(1)`` will involve
+Keeping the iterator/iterable retrieval methods as O(1) will involve
 writing custom replacements for the corresponding builtin dict helper types,
 just as proposed in :pep:`667`. As illustrated above, the implementations would
 be similar to the pseudo-code presented in :pep:`667`, but not identical (due to
@@ -1274,7 +1292,7 @@ Thanks to Nathaniel J. Smith for proposing the write-through proxy idea in
 PEP that attempted to avoid introducing such a proxy.
 
 Thanks to Steve Dower and Petr Viktorin for asking that more attention be paid
-to the developer experience of the proposed C API additions [8,13]_.
+to the developer experience of the proposed C API additions [8]_ [13]_.
 
 Thanks to Larry Hastings for the suggestion on how to use enums in the stable
 ABI while ensuring that they safely support typecasting from arbitrary
@@ -1283,7 +1301,7 @@ integers.
 Thanks to Mark Shannon for pushing for further simplification of the C level
 API and semantics, as well as significant clarification of the PEP text (and for
 restarting discussion on the PEP in early 2021 after a further year of
-inactivity) [10,11,12]_. Mark's comments that were ultimately published as
+inactivity) [10]_ [11]_ [12]_. Mark's comments that were ultimately published as
 :pep:`667` also directly resulted in several implementation efficiency improvements
 that avoid incurring the cost of redundant O(n) mapping refresh operations
 when the relevant mappings aren't used, as well as the change to ensure that
@@ -1293,58 +1311,44 @@ the state reported through the Python level ``f_locals`` API is never stale.
 References
 ==========
 
-.. [1] Broken local variable assignment given threads + trace hook + closure
-   (https://bugs.python.org/issue30744)
+.. [1] `Broken local variable assignment given threads + trace hook + closure
+   <https://github.com/python/cpython/issues/74929>`_
 
-.. [2] Clarify the required behaviour of ``locals()``
-   (https://bugs.python.org/issue17960)
+.. [3] `Updating function local variables from pdb is unreliable
+   <https://github.com/python/cpython/issues/5384)>`_
 
-.. [3] Updating function local variables from pdb is unreliable
-   (https://bugs.python.org/issue9633)
+.. [4] `CPython's Python API for installing trace hooks
+   <https://docs.python.org/dev/library/sys.html#sys.settrace>`_
 
-.. [4] CPython's Python API for installing trace hooks
-   (https://docs.python.org/dev/library/sys.html#sys.settrace)
+.. [5] `CPython's C API for installing trace hooks
+   <https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace>`_
 
-.. [5] CPython's C API for installing trace hooks
-   (https://docs.python.org/3/c-api/init.html#c.PyEval_SetTrace)
+.. [6] `PEP 558 reference implementation
+   <https://github.com/python/cpython/pull/3640/files>`_
 
-.. [6] PEP 558 reference implementation
-   (https://github.com/python/cpython/pull/3640/files)
+.. [7] `Nathaniel's review of possible function level semantics for locals()
+   <https://mail.python.org/pipermail/python-dev/2019-May/157738.html>`_
 
-.. [7] Nathaniel's review of possible function level semantics for locals()
-   (https://mail.python.org/pipermail/python-dev/2019-May/157738.html)
+.. [8] `Discussion of more intentionally designed C API enhancements
+   <https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3>`_
 
-.. [8] Discussion of more intentionally designed C API enhancements
-   (https://discuss.python.org/t/pep-558-defined-semantics-for-locals/2936/3)
+.. [9] `Disable automatic update of frame locals during tracing
+   <https://github.com/python/cpython/issues/86363>`_
 
-.. [9] Disable automatic update of frame locals during tracing
-   (https://bugs.python.org/issue42197)
+.. [10] `python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
+   <https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/>`_
 
-.. [10] python-dev thread: Resurrecting PEP 558 (Defined semantics for locals())
-   (https://mail.python.org/archives/list/python-dev@python.org/thread/TUQOEWQSCQZPUDV2UFFKQ3C3I4WGFPAJ/)
+.. [11] `python-dev thread: Comments on PEP 558
+   <https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/>`_
 
-.. [11] python-dev thread: Comments on PEP 558
-   (https://mail.python.org/archives/list/python-dev@python.org/thread/A3UN4DGBCOB45STE6AQBITJFW6UZE43O/)
+.. [12] `python-dev thread: More comments on PEP 558
+   <https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/>`_
 
-.. [12] python-dev thread: More comments on PEP 558
-   (https://mail.python.org/archives/list/python-dev@python.org/thread/7TKPMD5LHCBXGFUIMKDAUZELRH6EX76S/)
-
-.. [13] Petr Viktorin's suggestion to use an enum for ``PyLocals_Get``'s behaviour
-   (https://mail.python.org/archives/list/python-dev@python.org/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/)
+.. [13] `Petr Viktorin's suggestion to use an enum for PyLocals_Get's behaviour
+   <https://mail.python.org/archives/list/python-dev@python.org/message/BTQUBHIVE766RPIWLORC5ZYRCRC4CEBL/>`_
 
 Copyright
 =========
 
 This document is placed in the public domain or under the
 CC0-1.0-Universal license, whichever is more permissive.
-
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End: