From 6f583d265fad78218c9459e46fec8ddcaa345390 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 3 Feb 2022 21:11:45 -0600 Subject: [PATCH 1/5] PEP 12: Recommend and further explain using RST links, not footnotes --- pep-0001.txt | 3 +- pep-0012.rst | 95 ++++++++++++++++++++++++++++++++----------- pep-0012/pep-NNNN.rst | 2 +- 3 files changed, 75 insertions(+), 25 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 7911d3871ca..8147b97af28 100644 --- a/pep-0001.txt +++ b/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). diff --git a/pep-0012.rst b/pep-0012.rst index 2be95b510cb..cc37dbdd717 100644 --- a/pep-0012.rst +++ b/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,24 +433,71 @@ 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 `__ for more. + +which displays as: + + Visit the `website `__ 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 `_. + +which like the above, renders as: + + For further examples, see the `documentation `_. + +.. _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 @@ -463,18 +505,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: @@ -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: diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst index 5ba7d1ce61f..bd9f393aac0 100644 --- a/pep-0012/pep-NNNN.rst +++ b/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 From b7a0aaa8478c555db4c9b162fb5d1b08dd7b7f38 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 3 Feb 2022 21:34:49 -0600 Subject: [PATCH 2/5] PEP 1/12: Change name of References section to Footnotes in new PEPs --- pep-0001.txt | 6 +++--- pep-0012.rst | 12 ++++++------ pep-0012/pep-NNNN.rst | 4 ++-- pep2html.py | 6 +++--- .../pep_processor/transforms/pep_footer.py | 8 ++++---- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 8147b97af28..049dbab5be5 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -510,7 +510,7 @@ Each PEP should have the following parts/sections: ready for consideration are complete and reduces people duplicating prior discussion. -12. References -- A collection of footnotes referenced in the PEP, and +12. Footnotes -- 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 @@ -781,8 +781,8 @@ 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: diff --git a/pep-0012.rst b/pep-0012.rst index cc37dbdd717..d211cd05b8c 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -137,7 +137,7 @@ directions below. prohibition of tab characters and the indentation requirements. See "Suggested Sections" below for a template of sections to include. -- Update your References section, listing any footnotes and +- 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 @@ -488,7 +488,7 @@ which like the above, renders as: .. _pydocs: https://docs.python.org/ -An explicit target provides the URL. Put targets in a References section +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, @@ -562,8 +562,8 @@ followed by the footnote body. For example: .. code-block:: rst - References - ========== + Footnotes + ========= .. [1] Note that the footnote reference is a numbered one. @@ -581,8 +581,8 @@ other characters are allowed). For example: Refer to The TeXbook [#TeXbook]_ for more information. - References - ========== + Footnotes + ========= .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196. diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst index bd9f393aac0..c3d0c978141 100644 --- a/pep-0012/pep-NNNN.rst +++ b/pep-0012/pep-NNNN.rst @@ -75,8 +75,8 @@ Open Issues [Any points that are still being decided/discussed.] -References -========== +Footnotes +========= [A collection of footnotes referenced in the PEP, and a central place to list non-inline hyperlink targets.] diff --git a/pep2html.py b/pep2html.py index a35c9603e22..73e8cf470d5 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 @@ -511,8 +511,8 @@ def apply(self): 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 + if 'references' in title_words or 'footnotes' in title_words: + # Remove references/footnotes section if there are no displayed # footnotes (it only has title & link target nodes) if all(isinstance(ref_node, (nodes.title, nodes.target)) for ref_node in section): diff --git a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py index 7f8c0f01535..5fd039fb3c7 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, @@ -31,8 +31,8 @@ def apply(self) -> None: 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 + if "references" in title_words or "footnotes" in title_words: + # Remove references/footnotes section if there are no displayed # footnotes (it only has title & link target nodes) to_hoist = [] types = set() From 42e7d3b96bfc80e6fc2035e77f209d9ec98eee7e Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Thu, 3 Feb 2022 21:55:46 -0600 Subject: [PATCH 3/5] PEP 0, 1, 12: Update meta-PEPs to exemplify the current link guidance --- pep-0001.txt | 15 ++++++--------- pep-0012.rst | 15 ++++++++------- pep0/constants.py | 10 +++++----- 3 files changed, 19 insertions(+), 21 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 049dbab5be5..ea82bcdf778 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? ================================= @@ -785,18 +784,16 @@ 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 d211cd05b8c..bef14de51b8 100644 --- a/pep-0012.rst +++ b/pep-0012.rst @@ -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 @@ -680,15 +681,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 @@ -696,11 +697,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/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 = """ \ From bdee439eb3ef0804fbd230de5e345fa70436191d Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 15 Feb 2022 21:13:43 -0600 Subject: [PATCH 4/5] PEP 12: Implement reviewer feedback and make further improvements --- pep-0001.txt | 4 +-- pep-0012.rst | 35 +++++-------------- pep-0012/pep-NNNN.rst | 2 +- pep2html.py | 9 +++-- .../pep_processor/transforms/pep_footer.py | 9 +++-- 5 files changed, 20 insertions(+), 39 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index ea82bcdf778..492cda199e1 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -509,8 +509,8 @@ Each PEP should have the following parts/sections: ready for consideration are complete and reduces people duplicating prior discussion. -12. Footnotes -- A collection of footnotes referenced in the PEP, and - a central place to list non-inline hyperlink targets. +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). diff --git a/pep-0012.rst b/pep-0012.rst index bef14de51b8..cbcc00c5fa1 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 ======== @@ -469,8 +469,6 @@ which displays as: Visit the `website `__ 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 @@ -542,12 +540,17 @@ 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. Whitespace must precede the footnote reference. Leave a space between the footnote reference and the preceding word. @@ -566,28 +569,8 @@ followed by the footnote body. For example: Footnotes ========= - .. [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. - - Footnotes - ========= - .. [#TeXbook] Donald Knuth's *The TeXbook*, pages 195 and 196. - Footnotes and footnote references will be numbered automatically, and the numbers will always match. diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst index c3d0c978141..0ced89b223d 100644 --- a/pep-0012/pep-NNNN.rst +++ b/pep-0012/pep-NNNN.rst @@ -78,7 +78,7 @@ Open Issues Footnotes ========= -[A collection of footnotes referenced in the PEP, and a central place to list non-inline hyperlink targets.] +[A collection of footnotes cited in the PEP, and a place to list non-inline hyperlink targets.] Copyright diff --git a/pep2html.py b/pep2html.py index 73e8cf470d5..970c68dbafa 100755 --- a/pep2html.py +++ b/pep2html.py @@ -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 or 'footnotes' in title_words: - # Remove references/footnotes 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 5fd039fb3c7..80214f43e67 100644 --- a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py +++ b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py @@ -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 or "footnotes" in title_words: - # Remove references/footnotes 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": From be515247a4e01052ba76f0cbc00f15f26280be3a Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Wed, 16 Feb 2022 17:16:09 -0600 Subject: [PATCH 5/5] PEP 12: Further reduce excess detail and examples in hyperlinks section --- pep-0012.rst | 30 +++++++++--------------------- 1 file changed, 9 insertions(+), 21 deletions(-) diff --git a/pep-0012.rst b/pep-0012.rst index cbcc00c5fa1..d66bb240b9e 100644 --- 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,28 +459,17 @@ reference to avoid conflicting with other target names. For example: Visit the `website `__ for more. -which displays as: - - Visit the `website `__ 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 For further examples, see the `documentation `_. -which like the above, renders as: - - For further examples, see the `documentation `_. - -.. _pydocs: https://docs.python.org/ - 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 @@ -552,6 +535,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 +553,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.