Don't use numeric references.

Author: warsaw

pep-0553.rst

@@ -39,7 +39,7 @@ enter the debugger.  However this idiom has several disadvantages.
   debugging options, say if you're using an IDE or some other development
   environment.
 
-* Python linters (e.g. flake8 [1]_) complain about this line because it
+* Python linters (e.g. flake8 [linters]_) complain about this line because it
   contains two statements.  Breaking the idiom up into two lines further
   complicates the use of the debugger,
 
@@ -50,7 +50,7 @@ other languages, and utilizing a convention that already exists in Python.
 Proposal
 ========
 
-The JavaScript language provides a ``debugger`` statement [2]_ which enters
+The JavaScript language provides a ``debugger`` statement [java]_ which enters
 the debugger at the point where the statement appears.
 
 This PEP proposes a new built-in function called ``breakpoint()``
@@ -70,7 +70,7 @@ and it can be set to a different function to change the debugger that
 default value of ``sys.breakpointhook()`` to make it easy to reset.
 This exactly models the existing ``sys.displayhook()`` /
 ``sys.__displayhook__`` and ``sys.excepthook()`` /
-``sys.__excepthook__`` hooks [3]_.
+``sys.__excepthook__`` [hooks]_.
 
 The signature of the built-in is ``breakpoint(*args, **kws)``.  The positional
 and keyword arguments are passed straight through to ``sys.breakpointhook()``
@@ -100,7 +100,7 @@ can have various values:
   value may be a string with no dots, in which case it names a built-in
   callable, e.g. ``PYTHONBREAKPOINT=int``.  (Guido has expressed the
   preference for normal Python dotted-paths, not setuptools-style entry point
-  syntax [4]_ .)
+  syntax [syntax]_.)
 
 This environment variable allows external processes to control how breakpoints
 are handled.  Some uses cases include:
@@ -147,7 +147,7 @@ Evaluation of $PYTHONBREAKPOINT
 There has been some mailing list discussion around this topic.  The basic
 behavior as described above does not appear to be controversial.  Guido has
 expressed a preference for ``$PYTHONBREAKPOINT`` consultation happening in
-the default implementation of ``sys.breakpointhook``.
+the default implementation of ``sys.breakpointhook`` [envar]_.
 
 The one point of discussion relates to whether the value of
 ``$PYTHONBREAKPOINT`` should be loaded on interpreter start, and whether its
@@ -157,11 +157,11 @@ It is the PEP author's opinion that the environment variable need only be
 looked up at the time of use.  It is also the author's opinion that the value
 of the environment variable can be accessed each time ``sys.breakpointhook``
 is run, to allow for maximum functional flexibility.  Because this feature
-enters the debugger, any performance improvements for caching is negligible
-and does not outweigh the flexibility.  Further, because the special case of
-``PYTHONBREAKPOINT=0`` is fast-tracked, the no-op code path is quite fast, and
-should be in the noise given the function calls of ``breakpoint()`` ->
-``sys.breakpointhook()``.
+enters the debugger, any performance improvements for caching will be
+negligible and do not outweigh the flexibility.  Further, because the special
+case of ``PYTHONBREAKPOINT=0`` is fast-tracked, the no-op code path is quite
+fast, and should be in the noise given the function calls of ``breakpoint()``
+-> ``sys.breakpointhook()``.
 
 
 Breakpoint bytecode
@@ -191,7 +191,7 @@ it as handy as ``breakpoint.pm()``.
 Implementation
 ==============
 
-A pull request exists with the proposed implementation [5]_.
+A pull request exists with the proposed implementation [impl]_.
 
 
 Rejected alternatives
@@ -243,15 +243,23 @@ Version History
 References
 ==========
 
-.. [1] http://flake8.readthedocs.io/en/latest/
+.. [linters]
+   http://flake8.readthedocs.io/en/latest/
 
-.. [2] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
+.. [java]
+   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
 
-.. [3] https://docs.python.org/3/library/sys.html#sys.displayhook
+.. [hooks]
+   https://docs.python.org/3/library/sys.html#sys.displayhook
 
-.. [4] http://setuptools.readthedocs.io/en/latest/setuptools.html?highlight=console#automatic-script-creation
+.. [syntax]
+    http://setuptools.readthedocs.io/en/latest/setuptools.html?highlight=console#automatic-script-creation
 
-.. [5] https://github.com/python/cpython/pull/3355
+.. [impl]
+   https://github.com/python/cpython/pull/3355
+
+.. [envar]
+   https://mail.python.org/pipermail/python-dev/2017-September/149447.html
 
 
 Copyright