PEP 12: Recommend reST hyperlinks over footnotes (#2302)

pep-0001.txt

@@ -423,7 +423,6 @@ to development practices and other details. The precise process followed in
 these cases will depend on the nature and purpose of the PEP being updated.
 
 
-
 What belongs in a successful PEP?
 =================================
 
@@ -510,7 +509,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. Footnotes -- A collection of footnotes cited in the PEP, and
+    a 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).
@@ -780,22 +780,20 @@ Resources:
 * `Python Developer's Guide <https://devguide.python.org/>`_
 
 
-References and Footnotes
-========================
+Footnotes
+=========
 
 .. [1] This historical record is available by the normal git commands
-   for retrieving older revisions, and can also be browsed via HTTP here:
-   https://github.com/python/peps
+   for retrieving older revisions, and can also be browsed
+   `on GitHub <https://github.com/python/peps>`__.
 
 .. [2] More details on the PEP rendering and publication process can be found
-   in the PEPs repo README at
-   https://github.com/python/peps/blob/main/README.rst
+   in the `PEPs repo README
+   <https://github.com/python/peps/blob/main/README.rst>`__.
 
-.. _.github/CODEOWNERS:
-   https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+.. _.github/CODEOWNERS: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
-.. _issue tracker:
-   https://bugs.python.org/
+.. _issue tracker: https://bugs.python.org/
 
 .. _CC0-1.0-Universal: https://choosealicense.com/licenses/cc0-1.0/
 

pep-0012.rst

@@ -12,7 +12,7 @@ Post-History: 30-Aug-2002
 
 .. note::
     For those who have written a PEP before, there is a template_
-    (which is included as a file in the PEPs repository).
+    (which is included as a file in the `PEPs repository`_).
 
 Abstract
 ========
@@ -26,8 +26,9 @@ Note: if you are reading this PEP via the web, you should first grab
 the text (reStructuredText) source of this PEP in order to complete
 the steps below.  **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!**
 
-The source for this (or any) PEP can be found in the PEPs repository,
-viewable on the web at https://github.com/python/peps/ .
+The source for this (or any) PEP can be found in the
+`PEPs repository <https://github.com/python/peps/>`_,
+as well as via a link at the bottom of each PEP.
 
 
 Rationale
@@ -137,13 +138,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 Footnotes 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 +434,73 @@ 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 website``, you would write:
+
+.. code-block:: rst
+
+    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
+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:
 
-    In this paragraph, we refer to the `Python web site`_.
+.. code-block:: rst
+
+    Visit the `website <https://www.python.org/>`__ for more.
 
-An explicit target provides the URL.  Put targets in a References
-section at the end of the PEP, or immediately after the reference.
+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_>`_.
+
+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.
 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:
@@ -497,47 +523,42 @@ that for you.
 Footnotes
 ---------
 
-Footnote references consist of a left square bracket, a number, a
-right square bracket, and a trailing underscore:
+Footnote references consist of a left square bracket, a label, a
+right square bracket, and a trailing underscore.
+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:
 
 .. code-block:: rst
 
-    This sentence ends with a footnote reference [1]_.
+    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.
 
+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:
 
 .. code-block:: rst
 
-    References
-    ==========
-
-    .. [1] Note that the footnote reference is a numbered one.
-
-    .. [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:
-
-.. code-block:: rst
-
-    Refer to The TeXbook [#TeXbook]_ for more information.
+    .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
 
-    References
-    ==========
+which renders as
 
     .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196.
 
-
 Footnotes and footnote references will be numbered automatically, and
 the numbers will always match.
 
@@ -631,27 +652,27 @@ thoroughness, please see:
 
 * `A ReStructuredText Primer`__, a gentle introduction.
 
-  __ http://docutils.sourceforge.net/docs/rst/quickstart.html
+  __ https://docutils.sourceforge.io/docs/user/rst/quickstart.html
 
 * `Quick reStructuredText`__, a users' quick reference.
 
-  __ http://docutils.sourceforge.net/docs/rst/quickref.html
+  __ https://docutils.sourceforge.io/docs/user/rst/quickref.html
 
 * `reStructuredText Markup Specification`__, the final authority.
 
-  __ http://docutils.sourceforge.net/spec/rst/reStructuredText.html
+  __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
 
 The processing of reStructuredText PEPs is done using Docutils_.  If
 you have a question or require assistance with reStructuredText or
 Docutils, please `post a message`_ to the `Docutils-users mailing
 list`_.  The `Docutils project web site`_ has more information.
 
 .. _Docutils:
-.. _Docutils project web site: http://docutils.sourceforge.net/
+.. _Docutils project web site: https://docutils.sourceforge.io/
 .. _post a message:
    mailto:[email protected]?subject=PEPs
 .. _Docutils-users mailing list:
-   http://docutils.sf.net/docs/user/mailing-lists.html#docutils-users
+   https://docutils.sourceforge.io/docs/user/mailing-lists.html#docutils-users
 
 
 Copyright

pep-0012/pep-NNNN.rst

@@ -75,10 +75,10 @@ Open Issues
 [Any points that are still being decided/discussed.]
 
 
-References
-==========
+Footnotes
+=========
 
-[A collection of URLs used as references through the PEP.]
+[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.]
 
 
 Copyright

pep0/constants.py

@@ -21,14 +21,14 @@
 
 intro = """\
 This PEP contains the index of all Python Enhancement Proposals,
-known as PEPs.  PEP numbers are assigned by the PEP editors[1_], and
-once assigned are never changed.  The version control history [2_] of
-the PEP texts represent their historical record.
+known as PEPs.  PEP numbers are :pep:`assigned <1#pep-editors>` by the
+PEP editors, and once assigned are never changed.
+The `version control history`_ of the PEP texts represent
+their historical record.
 """
 
 references = """\
-.. [1] PEP 1: PEP Purpose and Guidelines
-.. [2] View PEP history online: https://github.com/python/peps
+.. _version control history: https://github.com/python/peps
 """
 
 footer = """\

pep2html.py

@@ -496,7 +496,7 @@ def apply(self):
 
 
 class PEPFooter(Transform):
-    """Remove the References section if it is empty when rendered."""
+    """Remove the References/Footnotes section if it is empty when rendered."""
 
     # Set low priority so ref targets aren't removed before they are needed
     default_priority = 999
@@ -510,14 +510,13 @@ def apply(self):
         for section in reversed(self.document):
             if not isinstance(section, nodes.section):
                 continue
-            title_words = section[0].astext().lower().split()
-            if 'references' in title_words:
-                # Remove references section if there are no displayed
-                # footnotes (it only has title & link target nodes)
+            title_words = {*section[0].astext().lower().split()}
+            if {"references", "footnotes"} & title_words:
+                # Remove references/footnotes sections if there is no displayed
+                # content (i.e. they only have title & link target nodes)
                 if all(isinstance(ref_node, (nodes.title, nodes.target))
                        for ref_node in section):
                     section.parent.remove(section)
-                break
 
 
 class PEPReader(standalone.Reader):

pep_sphinx_extensions/pep_processor/transforms/pep_footer.py

@@ -9,8 +9,8 @@
 class PEPFooter(transforms.Transform):
     """Footer transforms for PEPs.
 
-     - Removes the References section if it is empty when rendered.
-     - Creates a link to the (GitHub) source text.
+     - Remove the References/Footnotes section if it is empty when rendered.
+     - Create a link to the (GitHub) source text.
 
     Source Link:
         Create the link to the source file from the document source path,
@@ -30,10 +30,10 @@ def apply(self) -> None:
         for section in reversed(self.document[0]):
             if not isinstance(section, nodes.section):
                 continue
-            title_words = section[0].astext().lower().split()
-            if "references" in title_words:
-                # Remove references section if there are no displayed
-                # footnotes (it only has title & link target nodes)
+            title_words = {*section[0].astext().lower().split()}
+            if {"references", "footnotes"} & title_words:
+                # Remove references/footnotes sections if there is no displayed
+                # content (i.e. they only have title & link target nodes)
                 to_hoist = []
                 types = set()
                 for node in section:
@@ -43,7 +43,6 @@ def apply(self) -> None:
                 if types <= {nodes.title, nodes.target}:
                     section.parent.extend(to_hoist)
                     section.parent.remove(section)
-                break
 
         # Add link to source text and last modified date
         if pep_source_path.stem != "pep-0000":