PEP 12: Update to specify using the :pep: role to link to other PEPs

Author: CAM-Gerlach

pep-0012.rst

@@ -475,68 +475,71 @@ Footnotes containing the URLs from external targets will be generated
 automatically at the end of the References section of the PEP, along
 with footnote references linking the reference text to the footnotes.
 
-Text of the form "PEP x" or "RFC x" (where "x" is a number) will be
-linked automatically to the appropriate URLs.
+To refer to PEPs or RFCs, always use the ``:pep:`` and ``:rfc:`` roles,
+never hard-coded URLs.
+For example:
+
+.. code-block:: rst
+
+    See :pep:`1` for more information on how to write a PEP,
+    and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.
+
+This renders as:
+
+    See :pep:`1` for more information on how to write a PEP,
+    and :pep:`the Hyperlink section of PEP 12 <12#hyperlinks>` for how to link.
+
+PEP numbers in the text are never padded, and there is a space (not a dash)
+between "PEP" or "RFC" and the number; the above roles will take care of
+that for you.
 
 
 Footnotes
 ---------
 
 Footnote references consist of a left square bracket, a number, a
-right square bracket, and a trailing underscore::
+right square bracket, and a trailing underscore
+
+.. code-block:: rst
 
     This sentence ends with a footnote reference [1]_.
 
 Whitespace must precede the footnote reference.  Leave a space between
 the footnote reference and the preceding word.
 
-When referring to another PEP, include the PEP number in the body
-text, such as "PEP 1".  The title may optionally appear.  Add a
-footnote reference following the title.  For example::
-
-    Refer to PEP 1 [2]_ for more information.
-
-Add a footnote that includes the PEP's title and author.  It may
-optionally include the explicit URL on a separate line, but only in
-the References section.  Footnotes begin with ".. " (the explicit
+Footnotes begin with ".. " (the explicit
 markup start), followed by the footnote marker (no underscores),
-followed by the footnote body.  For example::
+followed by the footnote body.  For example:
+
+.. code-block:: rst
 
     References
     ==========
 
-    .. [2] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton
-       (http://www.python.org/dev/peps/pep-0001)
+    .. [1] Note that the footnote reference is a numbered one.
 
-If you decide to provide an explicit URL for a PEP, please use this as
-the URL template::
-
-    http://www.python.org/dev/peps/pep-xxxx
-
-PEP numbers in URLs must be padded with zeros from the left, so as to
-be exactly 4 characters wide; however, PEP numbers in the text are
-never padded.
+    .. [2] Donald Knuth's *The TeXBook*, pages 195 and 196.
 
 During the course of developing your PEP, you may have to add, remove,
 and rearrange footnote references, possibly resulting in mismatched
 references, obsolete footnotes, and confusion.  Auto-numbered
 footnotes allow more freedom.  Instead of a number, use a label of the
 form "#word", where "word" is a mnemonic consisting of alphanumerics
 plus internal hyphens, underscores, and periods (no whitespace or
-other characters are allowed).  For example::
+other characters are allowed).  For example:
+
+.. code-block:: rst
 
-    Refer to PEP 1 [#PEP-1]_ for more information.
+    Refer to The TeXBook [#TeXBook]_ for more information.
 
     References
     ==========
 
-    .. [#PEP-1] PEP 1, "PEP Purpose and Guidelines", Warsaw, Hylton
+    .. [#TeXBook] Donald Knuth's *The TeXBook*, pages 195 and 196.
 
-       http://www.python.org/dev/peps/pep-0001
 
 Footnotes and footnote references will be numbered automatically, and
-the numbers will always match.  Once a PEP is finalized, auto-numbered
-labels should be replaced by numbers for simplicity.
+the numbers will always match.
 
 
 Images