Initial patch as sent to py-dev

With a small but disasterous typo fixed though.

--HG--
branch : trunk

py/_code/assertion.py

@@ -5,12 +5,20 @@ BuiltinAssertionError = py.builtin.builtins.AssertionError
 
 
 def _format_explanation(explanation):
-    # uck!  See CallFunc for where \n{ and \n} escape sequences are used
+    """This formats an explanation
+
+    Normally all embedded newlines are escaped, however there are
+    three exceptions: \n{, \n} and \n~.  The first two are intended
+    cover nested explanations, see function and attribute explanations
+    for examples (.visit_Call(), visit_Attribute()).  The last one is
+    for when one explanation needs to span multiple lines, e.g. when
+    displaying diffs.
+    """
     raw_lines = (explanation or '').split('\n')
-    # escape newlines not followed by { and }
+    # escape newlines not followed by {, } and ~
     lines = [raw_lines[0]]
     for l in raw_lines[1:]:
-        if l.startswith('{') or l.startswith('}'):
+        if l.startswith('{') or l.startswith('}') or l.startswith('~'):
             lines.append(l)
         else:
             lines[-1] += '\\n' + l
@@ -28,11 +36,14 @@ def _format_explanation(explanation):
             stackcnt[-1] += 1
             stackcnt.append(0)
             result.append(' +' + '  '*(len(stack)-1) + s + line[1:])
-        else:
+        elif line.startswith('}'):
             assert line.startswith('}')
             stack.pop()
             stackcnt.pop()
             result[stack[-1]] += line[1:]
+        else:
+            assert line.startswith('~')
+            result.append('  '*len(stack) + line[1:])
     assert len(stack) == 1
     return '\n'.join(result)