PEP 12: Recommend and further explain using RST links, not footnotes

Author: CAM-Gerlach

pep-0001.txt

@@ -510,7 +510,8 @@ Each PEP should have the following parts/sections:
     ready for consideration are complete and reduces people duplicating
     prior discussion.
 
-12. References -- A collection of URLs used as references through the PEP.
+12. References -- A collection of footnotes referenced in the PEP, and
+    a central place to list non-inline hyperlink targets.
 
 13. Copyright/license -- Each new PEP must be placed under a dual license of
     public domain and CC0-1.0-Universal_ (see this PEP for an example).

pep-0012.rst

@@ -137,13 +137,8 @@ directions below.
   prohibition of tab characters and the indentation requirements.
   See "Suggested Sections" below for a template of sections to include.
 
-- Update your References and Copyright section.  Usually you'll place
-  your PEP into the public domain, in which case just leave the
-  Copyright section alone.  Alternatively, you can use the `Open
-  Publication License`__, but public domain is still strongly
-  preferred.
-
-  __ http://www.opencontent.org/openpub/
+- Update your References section, listing any footnotes and
+  non-inline link targets referenced by the text.
 
 - Leave the Emacs stanza at the end of this file alone, including the
   formfeed character ("^L", or ``\f``).
@@ -438,43 +433,92 @@ Hyperlinks
 ----------
 
 When referencing an external web page in the body of a PEP, you should
-include the title of the page in the text, with either an inline
-hyperlink reference to the URL or a footnote reference (see
-`Footnotes`_ below).  Do not include the URL in the body text of the
-PEP.
+include the title of the page or a suitable description in the text, with
+either an inline hyperlink or a separate explicit target with the URL.
+Do not include bare URLs in the body text of the PEP, and use HTTPS
+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::
+is a single word.  For example, to reference a hyperlink target named
+``Python web site``, 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`_.
 
-An explicit target provides the URL.  Put targets in a References
-section at the end of the PEP, or immediately after the reference.
+.. _Python web site: https://www.python.org/
+
+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
+you want to link, but before the closing backtick, with a space between the
+text and the opening backtick. You should also use a double-underscore after
+the closing backtick instead of a single one, which makes it an anonymous
+reference to avoid conflicting with other target names. For example:
+
+.. code-block:: rst
+
+    Visit the `website <https://www.python.org/>`__ for more.
+
+which displays as:
+
+    Visit the `website <https://www.python.org/>`__ for more.
+
+.. _Python web site: https://www.python.org/
+
+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
+
+    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/
+
+An explicit target provides the URL.  Put targets in a References section
+at the end of the PEP, or immediately after the paragraph with the reference.
 Hyperlink targets begin with two periods and a space (the "explicit
 markup start"), followed by a leading underscore, the reference text,
-a colon, and the URL (absolute or relative)::
+a colon, and the URL.
 
-    .. _Python web site: http://www.python.org/
+.. code-block:: rst
+
+    .. _Python web site: https://www.python.org/
+    .. _pydocs: https://docs.python.org/
 
 The reference text and the target text must match (although the match
 is case-insensitive and ignores differences in whitespace).  Note that
 the underscore trails the reference text but precedes the target text.
 If you think of the underscore as a right-pointing arrow, it points
 *away* from the reference and *toward* the target.
 
-The same mechanism can be used for internal references.  Every unique
-section title implicitly defines an internal hyperlink target.  We can
-make a link to the Abstract section like this::
+
+Internal and PEP/RFC Links
+--------------------------
+
+The same mechanism as hyperlinks can be used for internal references.
+Every unique section title implicitly defines an internal hyperlink target.
+We can make a link to the Abstract section like this:
+
+.. code-block:: rst
 
     Here is a hyperlink reference to the `Abstract`_ section.  The
     backquotes are optional since the reference text is a single word;
     we can also just write: Abstract_.
 
-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.
-
 To refer to PEPs or RFCs, always use the ``:pep:`` and ``:rfc:`` roles,
 never hardcoded URLs.
 For example:
@@ -507,6 +551,11 @@ right square bracket, and a trailing underscore:
 Whitespace must precede the footnote reference.  Leave a space between
 the footnote reference and the preceding word.
 
+Use footnotes for additional notes, explanations and caveats, as well as
+for references to books and other sources not readily available online.
+Native reST hyperlink targets or inline hyperlinks in the text should be
+used in preference to footnotes for including URLs to online resources.
+
 Footnotes begin with ".. " (the explicit
 markup start), followed by the footnote marker (no underscores),
 followed by the footnote body.  For example:

pep-0012/pep-NNNN.rst

@@ -78,7 +78,7 @@ Open Issues
 References
 ==========
 
-[A collection of URLs used as references through the PEP.]
+[A collection of footnotes referenced in the PEP, and a central place to list non-inline hyperlink targets.]
 
 
 Copyright