diff --git a/pep-0001.txt b/pep-0001.txt
index 7911d3871ca..492cda199e1 100644
--- a/pep-0001.txt
+++ b/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 `_
-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 `__.
.. [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
+ `__.
-.. _.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/
diff --git a/pep-0012.rst b/pep-0012.rst
index 2be95b510cb..d66bb240b9e 100644
--- a/pep-0012.rst
+++ b/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 `_,
+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,24 +434,52 @@ 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 `__ 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 `_.
+
+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
@@ -463,18 +487,20 @@ 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,15 +652,15 @@ 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
@@ -647,11 +668,11 @@ 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:docutils-users@lists.sourceforge.net?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
diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst
index 5ba7d1ce61f..0ced89b223d 100644
--- a/pep-0012/pep-NNNN.rst
+++ b/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
diff --git a/pep0/constants.py b/pep0/constants.py
index 108710d0927..3f48dd488b1 100644
--- a/pep0/constants.py
+++ b/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 = """ \
diff --git a/pep2html.py b/pep2html.py
index a35c9603e22..970c68dbafa 100755
--- a/pep2html.py
+++ b/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):
diff --git a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
index 7f8c0f01535..80214f43e67 100644
--- a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py
+++ b/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":