PEP-8 Update on Knuth style breaking of a long formula. #issue26780

Patch by Brandon Rhodes provides clarity and rationale for this suggestion.
Also fixes the example to use "+", "-" operators which have same precedence
level.

Reviewed by Guido van Rossum.

pep-0008.txt

@@ -253,31 +253,40 @@ Make sure to indent the continued line appropriately.
 Should a line break before or after a binary operator?
 ------------------------------------------------------
 
-For decades the recommended style has been to break after binary
-operators.  However, recent research unearthed recommendations by
-Donald Knuth to break *before* binary operators, in his writings about
-typesetting [3]_.  Therefore it is permissible to break before or
-after a binary operator, as long as the convention is consistent
-locally.  For new code Knuth's style is suggested.
+For decades the recommended style was to break after binary operators.
+But this can hurt readability in two ways: the operators tend to get
+scattered across different columns on the screen, and each operator is
+moved away from its operand and onto the previous line.  Here, the eye
+has to do extra work to tell which items are added and which are
+subtracted::
 
-Some examples of code breaking before binary Boolean operators::
+    # No: operators sit far away from their operands
+    income = (gross_wages +
+              taxable_interest +
+              (dividends - qualified_dividends) -
+              ira_deduction -
+              student_loan_interest)
 
-    class Rectangle(Blob):
+To solve this readability problem, mathematicians and their publishers
+follow the opposite convention.  Donald Knuth explains the traditional
+rule in his *Computers and Typesetting* series: "Although formulas
+within a paragraph always break after binary operations and relations,
+displayed formulas always break before binary operations" [3]_.
+
+Following the tradition from mathematics usually results in more
+readable code::
+
+    # Yes: easy to match operators with operands
+    income = (gross_wages
+              + taxable_interest
+              + (dividends - qualified_dividends)
+              - ira_deduction
+              - student_loan_interest)
+
+In Python code, it is permissible to break before or after a binary
+operator, as long as the convention is consistent locally.  For new
+code Knuth's style is suggested.
 
-        def __init__(self, width, height,
-                     color='black', emphasis=None, highlight=0):
-            if (width == 0
-                and height == 0
-                and color == 'red'
-                and emphasis == 'strong'
-                or highlight > 100):
-                raise ValueError("sorry, you lose")
-            if (width == 0 and height == 0
-                and (color == 'red' or emphasis is None)):
-                raise ValueError("I don't think so -- values are %s, %s" %
-                                 (width, height))
-            Blob.__init__(self, width, height,
-                          color, emphasis, highlight)
 
 Blank Lines
 -----------
@@ -1327,7 +1336,7 @@ References
 .. [2] Barry's GNU Mailman style guide
        http://barry.warsaw.us/software/STYLEGUIDE.txt
 
-.. [3] http://rhodesmill.org/brandon/slides/2012-11-pyconca/#laying-down-the-law
+.. [3] Donald Knuth's *The TeXBook*, pages 195 and 196.
 
 .. [4] http://www.wikipedia.com/wiki/CamelCase