PEP 595: replace mismatched references with inline links (#2534)

* PEP 595: replace mismatched references with inline links

* PEP 595: use plaintext instead of Python formatting

* PEP 595: remove redundant Emacs stanza

Author: hugovk

pep-0595.rst

@@ -28,9 +28,11 @@ informational PEP.
 Motivation
 ==========
 
-On May 14th, 2019 :pep:`581` has been accepted [#]_ without much
-public discussion and without a clear consensus [#]_.  The PEP
-contains factual errors and doesn't address some of the
+On May 14th, 2019 :pep:`581` has been `accepted
+<https://mail.python.org/pipermail/python-dev/2019-May/157399.html>`_
+without much public discussion and `without a clear consensus
+<https://mail.python.org/pipermail/python-committers/2019-May/006755.html>`_.
+The PEP contains factual errors and doesn't address some of the
 issues that the migration to GitHub Issues might present.
 
 Given the scope of the migration, the amount of work required,
@@ -98,13 +100,16 @@ on GitHub Issues.
 
 * **Nosy list autocomplete.**  The nosy list has an autocomplete
   feature that suggests maintainers and experts.  The suggestions
-  are automatically updated when the experts index [#]_ changes.
+  are automatically updated when the `experts index
+  <https://devguide.python.org/experts/>`_ changes.
 
 * **Dependencies and Superseders.** Roundup allows to specify
   dependencies that must be addressed before the current issues
   can be closed and a superseder issue to easily mark duplicates
-  [#]_.  The list of dependencies can also be used to create
-  meta-issues that references several other sub-issues [#]_.
+  (for example, `bpo-12078 <https://bugs.python.org/issue12078>`_).
+  The list of dependencies can also be used to create
+  meta-issues that references several other sub-issues
+  (for example, `bpo-26865 <https://bugs.python.org/issue26865>`_).
 
 
 Improving Roundup
@@ -115,7 +120,7 @@ and other desired features and discusses how they can be implemented
 by improving Roundup and/or our instance.
 
 * **REST API support.**  A REST API will make integration with other
-  services and the development of new tools and applications easiers.
+  services and the development of new tools and applications easier.
 
   Upstream Roundup now supports a REST API. Updating the tracker will
   make the REST API available.
@@ -125,15 +130,17 @@ by improving Roundup and/or our instance.
   It will also solve issues with confirmation emails being marked
   as spam, and provide two-factor authentication.
 
-  A patch to add this functionality is already available and is
-  being integrated at the time of writing [#]_.
+  A patch to add this functionality is `already available
+  <https://github.com/python/bugs.python.org/issues/7>`_
+  and is being integrated at the time of writing.
 
 * **Markdown support and message preview and editing.**  This feature
   will allow the use of Markdown in messages and the ability to
   preview the message before the submission and edit it afterward.
 
   This can be done, but it will take some work.  Possible solutions
-  have been proposed on the roundup-devel mailing list [#]_.
+  have been proposed on the `roundup-devel mailing list
+  <https://sourceforge.net/p/roundup/mailman/message/36667828/>`_.
 
 * **"Remove me from nosy list" button.**  Add a button on issue pages
   to remove self from the nosy list.
@@ -160,14 +167,18 @@ by improving Roundup and/or our instance.
 * **Add PR link to BPO emails.**  Currently bpo emails don't include
   links to the corresponding PRs.
 
-  A patch [#]_ is available to change the content of the bpo emails
-  from::
+  A `patch <https://mail.python.org/pipermail/tracker-discuss/2018-June/004547.html>`_
+  is available to change the content of the bpo emails from:
+
+  .. code-block:: text
 
      components: +Tkinter
      versions: +Python 3.4
      pull_requests: +42
 
-  to::
+  to:
+
+  .. code-block:: text
 
      components: +Tkinter
      versions: +Python 3.4
@@ -222,7 +233,8 @@ are currently supported:
   * The GitHub integration of Roundup automatically closes issues
     when a commit that contains "fixes issue <id>" is merged.
     (Alternative spellings such as "closes" or "bug" are also supported.)
-    See [#]_ for a recent example of this feature.
+    See `this message <https://bugs.python.org/issue36951#msg342882>`_
+    for a recent example of this feature.
 
 * "Support for permalinks, allowing easy quoting and copying &
   pasting of source code."
@@ -239,15 +251,19 @@ are currently supported:
     write and maintain bots.
 
     In some cases, bots are required to workaround GitHub's lack of
-    features rather than expanding. [#]_ was written
-    specifically to workaround GitHub's email integration.
+    features rather than expanding. `This webhook
+    <https://github.com/berkerpeksag/cpython-emailer-webhook>`_
+    was written specifically to workaround GitHub's email integration.
 
     Updating our bots to stay up-to-date with changes in the GitHub API
-    has also maintenance cost. [#]_ took two days to be fixed.
+    has also maintenance cost. `This recent incident caused by GitHub
+    <https://github.com/python/bedevere/pull/163>`_
+    took two days to be fixed.
 
     In addition, we will still need to maintain Roundup for bpo (even
     if it becomes read-only) and for the other trackers
-    we currently host/maintain (Jython [#]_ and Roundup [#]_).
+    we currently host/maintain (`Jython <https://bugs.jython.org/>`_
+    and `Roundup <https://issues.roundup-tracker.org/>`_).
 
 The "Issues with Roundup / bpo" section of :pep:`581` lists some issues
 that have already been fixed:
@@ -256,8 +272,11 @@ that have already been fixed:
   it puts heavy burden on the few existing maintainers in terms of
   reviewing, testing, and applying patches."
 
-  * While Roundup uses Mercurial by default, there is a git clone
-    available on GitHub [#]_.  Roundup also has CI available [#]_ [#]_.
+  * While Roundup uses Mercurial by default, there is a `git clone
+    available on GitHub <https://github.com/roundup-tracker/roundup>`_.
+    Roundup also has CI available on `Travis CI
+    <https://github.com/roundup-tracker/roundup>`_ and `Codecov
+    <https://codecov.io/gh/roundup-tracker/roundup/commits>`_.
 
 * "There is no REST API available. There is an open issue in Roundup for
   adding REST API. Last activity was in 2016."
@@ -271,7 +290,8 @@ that have already been fixed:
 
     This has now been changed to make the email addresses hidden for
     regular users too (Developers and Coordinators can still see them).
-    The "Email address" column from the user listing page [#]_ has been
+    The "Email address" column from the `user listing page
+    <https://bugs.python.org/user?@sort=username>`_ has been
     removed too.
 
 * "It sends a number of unnecessary emails and notifications, and it is
@@ -362,11 +382,12 @@ need to be addressed regardless of the approach used:
   redirects and preserve external links to GitHub issues.
 
 * **References preservation and updating.**  In addition to issue
-  references, bpo converts a number of other references into links,
+  references, bpo `converts a number of other references into links
+  <https://devguide.python.org/triaging/#generating-special-links-in-a-comment>`_,
   including message and PR IDs, changeset numbers, legacy SVN
   revision numbers, paths to files in the repo, files in tracebacks
   (detecting the correct branch), and links to devguide pages and
-  sections [#]_.
+  sections.
 
   Since Roundup converts references to links when messages are
   requested, it is possible to update the target and generate the
@@ -403,145 +424,38 @@ need to be addressed regardless of the approach used:
 * **Signal to noise ratio.**  Switching to GitHub Issues will
   likely increase the number of invalid reports and increase
   the triaging effort.  This concern has been raised in the past
-  in a Zulip topic [#]_.
+  in a `Zulip topic
+  <https://python.zulipchat.com/#narrow/stream/130206-pep581/topic/s.2Fn.20ratio>`_.
 
   There have been already cases where people posted comments on
   PRs that required moderators to mark them as off-topic or
   disruptive, delete them altogether, and even lock the
-  conversation [#]_.
+  conversation (for example, `this PR
+  <https://github.com/python/cpython/pull/9099>`_.
 
 * **Weekly tracker reports and stats.**  Roundup sends weekly reports
   to python-dev with a summary that includes new issues, recent
   issues with no replies, recent issues waiting for review, most
   discussed issues, closed issues, and deltas for open/closed/total
-  issue counts [#]_.  The report provides an easy way to keep track
+  issue counts (for example, see `this summary
+  <https://mail.python.org/pipermail/python-dev/2019-May/157483.html>`_).
+  The report provides an easy way to keep track
   of the tracker activity and to make sure that issues that require
   attention are noticed.
 
-  The data collect by the weekly report is also use to generate
-  statistics and graphs that can be used to gain new insights [#]_.
+  The data collect by the weekly report is also used to generate
+  `statistics and graphs <https://bugs.python.org/issue?@template=stats>`_
+  that can be used to gain new insights.
 
 * **bpo-related MLs.**  There are currently two mailing lists where
   bpo posts new tracker issues and all messages respectively:
-  ``new-bugs-announce`` [#]_ and ``python-bugs-list`` [#]_.  A new system
-  will need to be developed to preserve this functionality.  These MLs
+  `new-bugs-announce <https://mail.python.org/mailman/listinfo/new-bugs-announce>`_
+  and `python-bugs-list <https://mail.python.org/mailman/listinfo/python-bugs-list>`_.
+  A new system will need to be developed to preserve this functionality.  These MLs
   offer additional ways to keep track of the tracker activity.
 
 
-References
-==========
-
-.. [#] [Python-Dev] PEP 581 (Using GitHub issues for CPython) is accepted
-
-   https://mail.python.org/pipermail/python-dev/2019-May/157399.html
-
-.. [#] [python-committers] [Python-Dev] PEP 581 (Using GitHub issues
-   for CPython) is accepted
-
-   https://mail.python.org/pipermail/python-committers/2019-May/006755.html
-
-.. [#] Experts Index -- Python Devguide
-
-   https://devguide.python.org/experts/
-
-.. [#] An example of superseded issues:
-   "re.sub() replaces only several matches"
-
-   https://bugs.python.org/issue12078
-
-.. [#] An example of meta issue using dependencies to track sub-issues:
-   "Meta-issue: support of the android platform""
-
-   https://bugs.python.org/issue26865
-
-.. [#] Support logging in with GitHub
-
-   https://github.com/python/bugs.python.org/issues/7
-
-.. [#] Re: [Roundup-devel] PEP 581 and Google Summer of Code
-
-   https://sourceforge.net/p/roundup/mailman/message/36667828/
-
-.. [#] [Tracker-discuss] [issue624] bpo emails contain useless non-github
-       pull_request number - users want a link to actual github PR
-
-   https://mail.python.org/pipermail/tracker-discuss/2018-June/004547.html
-
-.. [#] The commit reported in msg342882 closes the issue (see the history below)
-
-   https://bugs.python.org/issue36951#msg342882
-
-.. [#] The cpython-emailer-webhook project
-
-   https://github.com/berkerpeksag/cpython-emailer-webhook
-
-.. [#] A recent incident caused by GitHub
-
-   https://github.com/python/bedevere/pull/163
-
-.. [#] Jython issue tracker
-
-   https://bugs.jython.org/
-
-.. [#] Roundup issue tracker
-
-   https://issues.roundup-tracker.org/
-
-.. [#] GitHub clone of Roundup
-
-   https://github.com/roundup-tracker/roundup
-
-.. [#] Travis-CI for Roundup
-
-   https://travis-ci.org/roundup-tracker/roundup) and codecov
-
-.. [#] Codecov for Roundup
-
-   https://codecov.io/gh/roundup-tracker/roundup/commits
-
-.. [#] User listing -- Python tracker
-
-   https://bugs.python.org/user?@sort=username
-
-.. [#] Generating Special Links in a Comment -- Python Devguide
-
-   https://devguide.python.org/triaging/#generating-special-links-in-a-comment
-
-.. [#] The New-bugs-announce mailing list
-
-   https://mail.python.org/mailman/listinfo/new-bugs-announce
-
-.. [#] The Python-bugs-list mailing list
-
-   https://mail.python.org/mailman/listinfo/python-bugs-list
-
-.. [#] An example of [Python-Dev] Summary of Python tracker Issues
-
-   https://mail.python.org/pipermail/python-dev/2019-May/157483.html
-
-.. [#] Issues stats -- Python tracker
-
-   https://bugs.python.org/issue?@template=stats
-
-.. [#] s/n ratio -- Python -- Zulip
-
-   https://python.zulipchat.com/#narrow/stream/130206-pep581/topic/s.2Fn.20ratio
-
-.. [#] For example, this and other related PRs:
-
-   https://github.com/python/cpython/pull/9099
-
-
 Copyright
 =========
 
 This document has been placed in the public domain.
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End: