PEP 12: Further reduce excess detail and examples in hyperlinks section

CAM-Gerlach · CAM-Gerlach · commit fa28adb7c796 · 2022-02-16T17:16:09.000-06:00
diff --git a/pep-0012.rst b/pep-0012.rst
@@ -442,17 +442,11 @@ links wherever available.
 Hyperlink references use backquotes and a trailing underscore to mark
 up the reference text; backquotes are optional if the reference text
 is a single word.  For example, to reference a hyperlink target named
-``Python web site``, you would write:
+``Python website``, you would write:
 
 .. code-block:: rst
 
-    In this paragraph, we refer to the `Python web site`_.
-
-which renders as:
-
-    In this paragraph, we refer to the `Python web site`_.
-
-.. _Python web site: https://www.python.org/
+    In this paragraph, we refer to the `Python website`_.
 
 If you intend to only reference a link once, and want to define it inline
 with the text, insert the link into angle brackets (``<>``) after the text
@@ -465,27 +459,17 @@ reference to avoid conflicting with other target names. For example:
 
     Visit the `website <https://www.python.org/>`__ for more.
 
-which displays as:
-
-    Visit the `website <https://www.python.org/>`__ for more.
-
 If you want to use one link multiple places with different linked text,
 or want to ensure you don't have to update your link target names when
 changing the linked text, include the target name within angle brackets
 following the text to link, *with an underscore after the target name
 but before the closing angle bracket* (or the link **will not work**).
-
 For example:
 
 .. code-block:: rst
+   :class: test-class
 
-    For further examples, see the `documentation <pydocs_>`_.
-
-which like the above, renders as:
-
-    For further examples, see the `documentation <pydocs_>`_.
-
-.. _pydocs: https://docs.python.org/
+   For further examples, see the `documentation <pydocs_>`_.
 
 An explicit target provides the URL.  Put targets in the Footnotes section
 at the end of the PEP, or immediately after the paragraph with the reference.
@@ -552,6 +536,10 @@ For example:
 
     Refer to The TeXbook [#TeXbook]_ for more information.
 
+which renders as
+
+    Refer to The TeXbook [#TeXbook]_ for more information.
+
 Whitespace must precede the footnote reference.  Leave a space between
 the footnote reference and the preceding word.
 
@@ -566,8 +554,9 @@ followed by the footnote body.  For example:
 
 .. code-block:: rst
 
-    Footnotes
-    =========
+    .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
+
+which renders as
 
     .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
 
