Limit line length to 80 & clean-up nearby formatting. (python#282)

* Limit line length to 80 or less & nearby clean-up.

Wide-ranging but essentially trivial adjustment of line length. Also
fixes top-level indenting in gdb.rst particularly.

* Avoid whitespace elision by editor before literal block

Author: jeff5

Diff for: buildbots.rst

@@ -4,8 +4,8 @@ Continuous Integration
 ======================
 
 To assert that there are no regressions in the :doc:`development and maintenance
-branches <devcycle>`, Python has a set of dedicated machines (called *buildbots* or
-*build slaves*) used for continuous integration.  They span a number of
+branches <devcycle>`, Python has a set of dedicated machines (called *buildbots*
+or *build slaves*) used for continuous integration.  They span a number of
 hardware/operating system combinations.  Furthermore, each machine hosts
 several *builders*, one per active branch: when a new change is pushed
 to this branch on the public Mercurial repository, all corresponding builders
@@ -186,8 +186,8 @@ offenders:
 When you think a failure might be transient, it is recommended you confirm by
 waiting for the next build.  Still, even if the failure does turn out sporadic
 and unpredictable, the issue should be reported on the bug tracker; even
-better if it can be diagnosed and suppressed by fixing the test's implementation,
-or by making its parameters - such as a timeout - more robust.
+better if it can be diagnosed and suppressed by fixing the test's
+implementation, or by making its parameters - such as a timeout - more robust.
 
 
 Custom builders

Diff for: committing.rst

@@ -212,12 +212,12 @@ repositories means you have to be more careful with your workflow:
   This exception should not be abused and be left only for very simple changes.
 
 * You should not commit directly into the ``master`` branch, or any of the
-  maintenance branches (currently ``2.7`` or ``3.6``).  You should commit against
-  your own feature branch, and create a pull request.
+  maintenance branches (currently ``2.7`` or ``3.6``).
+  You should commit against your own feature branch, and create a pull request.
 
-It is recommended to keep a fork of the main repository around, as it allows simple
-reversion of all local changes (even "committed" ones) if your local clone gets
-into a state you aren't happy with.
+It is recommended to keep a fork of the main repository around, as it allows
+simple reversion of all local changes (even "committed" ones) if your local
+clone gets into a state you aren't happy with.
 
 
 .. _Git: https://git-scm.com/
@@ -238,15 +238,17 @@ new features.  The other branches only receive bug fixes or security fixes.
 Backporting Changes to an Older Version
 ---------------------------------------
 
-When it is determined that a pull request needs to be backported into one or more of
-the maintenance branches, a core developer can apply the labels ``needs backport to X.Y``
-to the pull request.
+When it is determined that a pull request needs to be backported into one or
+more of the maintenance branches, a core developer can apply the labels
+``needs backport to X.Y`` to the pull request.
 
-After the pull request has been merged, it can be backported using cherry_picker.py_.
+After the pull request has been merged, it can be backported using
+cherry_picker.py_.
 
-The commit hash can be obtained from the original pull request, or by using ``git log``
-on the ``master`` branch.  To display the 10 most recent commit hashes and their first
-line of the commit message::
+The commit hash can be obtained from the original pull request, or by using
+``git log`` on the ``master`` branch.
+To display the 10 most recent commit hashes and their first line of the commit
+message::
 
    git log -10 --oneline
 

Diff for: communication.rst

@@ -26,10 +26,10 @@ Python-ideas_ is a mailing list open to the public to discuss ideas on changing
 Python. If a new idea does not start here (or python-list_, discussed below),
 it will get redirected here.
 
-Sometimes people post new ideas to python-list_ to gather community opinion before
-heading to python-ideas_. The list is also sometimes known as comp.lang.python,
-the name of the newsgroup it mirrors (it is also known by the abbreviation
-c.l.py).
+Sometimes people post new ideas to python-list_ to gather community opinion
+before heading to python-ideas_. The list is also sometimes known as
+comp.lang.python, the name of the newsgroup it mirrors (it is also known by
+the abbreviation c.l.py).
 
 The python-committers_ mailing list is a private mailing list for core
 developers (the archives are publicly available).

Diff for: compiler.rst

@@ -170,11 +170,11 @@ very beginning of the compiler or the end, you need to care about how the arena
 works.  All code relating to the arena is in either :file:`Include/pyarena.h` or
 :file:`Python/pyarena.c`.
 
-``PyArena_New()`` will create a new arena.  The returned ``PyArena`` structure will
-store pointers to all memory given to it.  This does the bookkeeping of what
-memory needs to be freed when the compiler is finished with the memory it used.
-That freeing is done with ``PyArena_Free()``.  This only needs to be called in
-strategic areas where the compiler exits.
+``PyArena_New()`` will create a new arena.  The returned ``PyArena`` structure
+will store pointers to all memory given to it.  This does the bookkeeping of
+what memory needs to be freed when the compiler is finished with the memory it
+used. That freeing is done with ``PyArena_Free()``.  This only needs to be
+called in strategic areas where the compiler exits.
 
 As stated above, in general you should not have to worry about memory
 management when working on the compiler.  The technical details have been
@@ -367,23 +367,24 @@ bytecode step of the compiler.  Several pieces of code throughout Python depend
 on having correct information about what bytecode exists.
 
 First, you must choose a name and a unique identifier number.  The official
-list of bytecode can be found in :file:`Include/opcode.h`.  If the opcode is to take
-an argument, it must be given a unique number greater than that assigned to
+list of bytecode can be found in :file:`Include/opcode.h`.  If the opcode is to
+take an argument, it must be given a unique number greater than that assigned to
 ``HAVE_ARGUMENT`` (as found in :file:`Include/opcode.h`).
 
 Once the name/number pair has been chosen and entered in Include/opcode.h,
 you must also enter it into :file:`Lib/opcode.py` and
 :file:`Doc/library/dis.rst`.
 
 With a new bytecode you must also change what is called the magic number for
-.pyc files.  The variable ``MAGIC`` in :file:`Python/import.c` contains the number.
+.pyc files.  The variable ``MAGIC`` in :file:`Python/import.c` contains the
+number.
 Changing this number will lead to all .pyc files with the old ``MAGIC``
 to be recompiled by the interpreter on import.
 
 Finally, you need to introduce the use of the new bytecode.  Altering
 :file:`Python/compile.c` and :file:`Python/ceval.c` will be the primary places
-to change. But you will also need to change the 'compiler' package.  The key files
-to do that are :file:`Lib/compiler/pyassem.py` and
+to change. But you will also need to change the 'compiler' package.
+The key files to do that are :file:`Lib/compiler/pyassem.py` and
 :file:`Lib/compiler/pycodegen.py`.
 
 If you make a change here that can affect the output of bytecode that
@@ -392,10 +393,10 @@ sure to delete your old .py(c|o) files!  Even though you will end up changing
 the magic number if you change the bytecode, while you are debugging your work
 you will be changing the bytecode output without constantly bumping up the
 magic number.  This means you end up with stale .pyc files that will not be
-recreated.  Running
-``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc files you
-have, forcing new ones to be created and thus allow you test out your new
-bytecode properly.
+recreated.
+Running ``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc
+files you have, forcing new ones to be created and thus allow you test out your
+new bytecode properly.
 
 
 Code Objects

Diff for: devcycle.rst

@@ -164,11 +164,11 @@ bug fixes can now be committed.  This is when core developers should concentrate
 on the task of fixing regressions and other new issues filed by users who have
 downloaded the alpha and beta releases.
 
-Being in beta can be viewed much like being in RC_ but without the extra overhead
-of needing commit reviews.
+Being in beta can be viewed much like being in RC_ but without the extra
+overhead of needing commit reviews.
 
-Please see the note in the `In-development (main) branch`_ section above
-for new information about the creation of the 3.5 maintenance branch during beta.
+Please see the note in the `In-development (main) branch`_ section above for
+new information about the creation of the 3.5 maintenance branch during beta.
 
 
 .. _rc:
@@ -179,8 +179,8 @@ Release Candidate (RC)
 A branch preparing for an RC release can only have bugfixes applied that have
 been reviewed by other core developers.  Generally, these issues must be
 severe enough (e.g. crashes) that they deserve fixing before the final release.
-All other issues should be deferred to the next development cycle, since stability
-is the strongest concern at this point.
+All other issues should be deferred to the next development cycle, since
+stability is the strongest concern at this point.
 
 You **cannot** skip the peer review during an RC, no matter how small! Even if
 it is a simple copy-and-paste change, **everything** requires peer review from

Diff for: developers.rst

@@ -14,9 +14,9 @@ change or granted access.  The procedure for adding or removing users is
 described in :ref:`altering-access`.
 
 Note, when giving new commit permissions, be sure to get a contributor agreement
-from the committer.  See https://www.python.org/psf/contrib/ for details.  Commit
-privileges should not be given until the contributor agreement has been signed
-and received.
+from the committer.  See https://www.python.org/psf/contrib/ for details.
+Commit privileges should not be given until the contributor agreement has been
+signed and received.
 
 This file is encoded in UTF-8.  If the usual form for a name is not in
 a Latin or extended Latin alphabet, make sure to include an ASCII

Diff for: docquality.rst

@@ -8,7 +8,8 @@ keeping a high level of quality takes a lot of effort. Help is always
 appreciated with the documentation, and it requires little programming
 experience (with or without Python).
 
-:ref:`Documenting Python <documenting>` covers the details of how Python's documentation works.
+:ref:`Documenting Python <documenting>` covers the details of how Python's
+documentation works.
 It includes an explanation of the markup used (although you can figure a lot
 out simply by looking at pre-existing documentation) and :ref:`how to build
 <building-doc>` the documentation (which allows you to see how your changes
@@ -25,8 +26,8 @@ subscribing to the
 Documentation issues reported on the `issue tracker`_ are sent here as well as
 some bug reports being directly emailed to the mailing list. There is also the
 `[email protected] mailing list
-<https://mail.python.org/mailman/listinfo/doc-sig>`_ which discusses the
-documentation toolchain, projects, standards, etc.
+<https://mail.python.org/mailman/listinfo/doc-sig>`_
+which discusses the documentation toolchain, projects, standards, etc.
 
 
 Helping with issues filed on the issue tracker
@@ -38,10 +39,10 @@ typos, to unclear documentation, to something completely lacking documentation.
 
 If you decide to tackle a documentation issue, you can simply submit a
 :doc:`pull request <pullrequest>` for the issue. If you are worried that someone
-else might be working simultaneously on the issue, simply leave a comment on the issue
-saying you are going to try and create a pull request and roughly how long you think
-you will take to do it (this allows others to take on the issue if you happen
-to forget or lose interest).
+else might be working simultaneously on the issue, simply leave a comment on the
+issue saying you are going to try and create a pull request and roughly how long
+you think you will take to do it (this allows others to take on the issue if you
+happen to forget or lose interest).
 
 .. _issue tracker: https://bugs.python.org
 .. _documentation issues: https://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=&priority=&%40group=priority&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search
@@ -58,9 +59,10 @@ from Python 2).
 
 If you decide to proofread, then read a section of the documentation from start
 to finish, filing issues in the issue tracker for each problem you find. Simple
-typos don't require an issue of their own, instead submit a pull request directly.
-Don't file a single issue for an entire section containing multiple problems as that
-makes it harder to break the work up for multiple people to help with.
+typos don't require an issue of their own, instead submit a pull request
+directly.
+Don't file a single issue for an entire section containing multiple problems as
+that makes it harder to break the work up for multiple people to help with.
 
 
 .. _helping-with-the-developers-guide:

Diff for: documenting.rst

@@ -171,7 +171,8 @@ Bad example (creating worry in the mind of a reader):
     excessive resource consumption.  Never rely on reference counting to
     automatically close a file.
 
-Good example (establishing confident knowledge in the effective use of the language):
+Good example (establishing confident knowledge in the effective use of the
+language):
 
     A best practice for using files is use a try/finally pair to explicitly
     close a file after it is used.  Alternatively, using a with-statement can
@@ -222,8 +223,8 @@ a typical use case.  For instance, the :meth:`str.rpartition` method is better
 demonstrated with an example splitting the domain from a URL than it would be
 with an example of removing the last word from a line of Monty Python dialog.
 
-The ellipsis for the :py:data:`sys.ps2` secondary interpreter prompt should only be
-used sparingly, where it is necessary to clearly differentiate between input
+The ellipsis for the :py:data:`sys.ps2` secondary interpreter prompt should only
+be used sparingly, where it is necessary to clearly differentiate between input
 lines and output lines.  Besides contributing visual clutter, it makes it
 difficult for readers to cut-and-paste examples so they can experiment with
 variations.
@@ -456,7 +457,9 @@ the extension mechanisms of reST, and Sphinx makes heavy use of it.
 
 Basically, a directive consists of a name, arguments, options and content. (Keep
 this terminology in mind, it is used in the next chapter describing custom
-directives.)  Looking at this example, ::
+directives.)  Looking at this example,
+
+::
 
    .. function:: foo(x)
                  foo(y, z)
@@ -853,8 +856,8 @@ Syntax highlighting is handled in a smart way:
 
 Longer displays of verbatim text may be included by storing the example text in
 an external file containing only plain text.  The file may be included using the
-``literalinclude`` directive. [1]_ For example, to include the Python source file
-:file:`example.py`, use::
+``literalinclude`` directive. [1]_ For example, to include the Python source
+file :file:`example.py`, use::
 
    .. literalinclude:: example.py
 
@@ -895,8 +898,8 @@ a matching identifier is found:
 
 .. describe:: mod
 
-   The name of a module; a dotted name may be used.  This should also be used for
-   package names.
+   The name of a module; a dotted name may be used.  This should also be used
+   for package names.
 
 .. describe:: func
 
@@ -1358,8 +1361,8 @@ pair
    namely ``loop; statement`` and ``statement; loop``.
 triple
    Likewise, ``triple: module; search; path`` is a shortcut that creates three
-   index entries, which are ``module; search path``, ``search; path, module`` and
-   ``path; module search``.
+   index entries, which are ``module; search path``, ``search; path, module``
+   and ``path; module search``.
 module, keyword, operator, object, exception, statement, builtin
    These all create two index entries.  For example, ``module: hashlib``
    creates the entries ``module; hashlib`` and ``hashlib; module``.  The
@@ -1418,8 +1421,8 @@ The following is an example taken from the Python Reference Manual::
 Substitutions
 -------------
 
-The documentation system provides three substitutions that are defined by default.
-They are set in the build configuration file :file:`conf.py`.
+The documentation system provides three substitutions that are defined by
+default. They are set in the build configuration file :file:`conf.py`.
 
 .. describe:: |release|
 
@@ -1491,7 +1494,7 @@ Without make
 
 Install the Sphinx package and its dependencies from PyPI.
 
-Then, from the ``Docs`` directory, run ::
+Then, from the ``Docs`` directory, run::
 
    sphinx-build -b<builder> . build/<builder>
 

Diff for: fixingissues.rst

@@ -5,9 +5,9 @@ Fixing "easy" Issues (and Beyond)
 
 When you feel comfortable enough to want to help tackle issues by trying to
 create a patch to fix an issue, you can start by looking at the `"easy"
-issues`_. These issues *should* be ones where it should take no longer than a day
-or weekend to fix. But because the "easy" classification is typically done at
-triage time it can turn out to be inaccurate, so do feel free to leave a
+issues`_. These issues *should* be ones where it should take no longer than a
+day or weekend to fix. But because the "easy" classification is typically done
+at triage time it can turn out to be inaccurate, so do feel free to leave a
 comment if you think the classification no longer applies.
 
 For the truly adventurous looking for a challenge, you can look for issues that