Closing issue1761.
Surprising behaviour of the "$" regexp: it matches the
end of the string, AND just before the newline at the end
of the string::

    re.sub('$', '#', 'foo\n') == 'foo#\n#'

Python is consistent with Perl and the pcre library, so
we just document it.
Guido prefers "\Z" to match only the end of the string.
diff --git a/Lib/test/test_re.py b/Lib/test/test_re.py
index 3056ef3..a2470cd 100644
--- a/Lib/test/test_re.py
+++ b/Lib/test/test_re.py
@@ -671,6 +671,18 @@
         q = p.match(upper_char)
         self.assertNotEqual(q, None)
 
+    def test_dollar_matches_twice(self):
+        "$ matches the end of string, and just before the terminating \n"
+        pattern = re.compile('$')
+        self.assertEqual(pattern.sub('#', 'a\nb\n'), 'a\nb#\n#')
+        self.assertEqual(pattern.sub('#', 'a\nb\nc'), 'a\nb\nc#')
+        self.assertEqual(pattern.sub('#', '\n'), '#\n#')
+
+        pattern = re.compile('$', re.MULTILINE)
+        self.assertEqual(pattern.sub('#', 'a\nb\n' ), 'a#\nb#\n#' )
+        self.assertEqual(pattern.sub('#', 'a\nb\nc'), 'a#\nb#\nc#')
+        self.assertEqual(pattern.sub('#', '\n'), '#\n#')
+
 
 def run_re_tests():
     from test.re_tests import benchmarks, tests, SUCCEED, FAIL, SYNTAX_ERROR