Added support for multiple attributions in a physical block quote (indented text block), dividing it into multiple logical block quotes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4522 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 40 insertions, 21 deletions

diff --git a/docs/dev/todo.txt b/docs/dev/todo.txt
index 3137584d2..37de05034 100644
--- a/docs/dev/todo.txt
+++ b/docs/dev/todo.txt
@@ -782,17 +782,6 @@ __ rst/alternatives.html#or-not-to-do
 
   See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
 
-* Allow multiple block quotes, only separated by attributions
-  (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.::
-
-      quote 1
-
-      ---Attrib 1
-
-      quote 2
-
-      ---Attrib 2
-
 * Change the specification so that more punctuation is allowed
   before/after inline markup start/end string
   (http://article.gmane.org/gmane.text.docutils.cvs/3824).
diff --git a/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt
index 1445619b3..48f8e741e 100644
--- a/docs/ref/rst/restructuredtext.txt
+++ b/docs/ref/rst/restructuredtext.txt
@@ -1215,9 +1215,9 @@ Block Quotes
 Doctree element: block_quote, attribution.
 
 A text block that is indented relative to the preceding text, without
-markup indicating it to be a literal block, is a block quote.  All
-markup processing (for body elements and inline markup) continues
-within the block quote::
+preceding markup indicating it to be a literal block or other content,
+is a block quote.  All markup processing (for body elements and inline
+markup) continues within the block quote::
 
     This is an ordinary paragraph, introducing a block quote.
 
@@ -1225,10 +1225,38 @@ within the block quote::
 
         -- Sherlock Holmes
 
-If the final block of a block quote begins with "--", "---", or a true
-em-dash (flush left within the block quote), it is interpreted as an
-attribution.  If the attribution consists of multiple lines, the left
-edges of the second and subsequent lines must align.
+A block quote may end with an attribution: a text block beginning with
+"--", "---", or a true em-dash, flush left within the block quote.  If
+the attribution consists of multiple lines, the left edges of the
+second and subsequent lines must align.
+
+Multiple block quotes may occur consecutively if terminated with
+attributions.
+
+    Unindented paragraph.
+
+        Block quote 1.
+
+        -- Attribution 1
+
+        Block quote 2.
+
+`Empty comments`_ may be used to explicitly terminate preceding
+constructs that would otherwise consume a block quote::
+
+    * List item.
+
+    ..
+
+        Block quote 3.
+
+Empty comments may also be used to separate block quotes::
+
+        Block quote 4.
+
+    ..
+
+        Block quote 5.
 
 Blank lines are required before and after a block quote, but these
 blank lines are not included as part of the block quote.
@@ -2240,10 +2268,12 @@ constructs is recognized, leave the ".." on a line by itself::
     ..
        |even| this:: !
 
+.. _empty comments:
+
 An explicit markup start followed by a blank line and nothing else
-(apart from whitespace) is an "empty comment".  It serves to terminate
-a preceding construct, and does **not** consume any indented text
-following.  To have a block quote follow a list or any indented
+(apart from whitespace) is an "_`empty comment`".  It serves to
+terminate a preceding construct, and does **not** consume any indented
+text following.  To have a block quote follow a list or any indented
 construct, insert an unindented empty comment in-between.
 
 Syntax diagram::