[Doc-SIG] Comments within lists

[Garth Kidd]

DISCLAIMER: I only just checked back and noticed that there was a
particular DTD the output should conform to. Cool, but this message
might be redundant when I finally read the DTD. Or maybe not.

<laughter>

It just occurred to me that we could well end up producing an "edge
cases" appendix to the reStructuredText specification by pulling
reStructuredText docstrings out of the unit tests for the parser. :)

Anyway, on with the story. This input::

	A paragraph.

	.. A comment with two paragraphs.

         Yep.

	Another paragraph.

... should render to XML as something like::

	<p>A paragraph.</p>
	<comment>
	  <p>A comment with two paragraphs.</p>
	  <p>Yep.</p>
	</comment>
	<p>Another paragraph.</p>

... so a single-paragraph comment, for consistency::

	<comment>
	  <p>A comment with two paragraphs.</p>
	</comment>

... and a comment between two paragraphs in a list item::

	<bullet_list>
	  <list_item>
	    <p>The first paragraph of the list item.</p>
	      <comment>
	        <p>A comment with two paragraphs.</p>
	        <p>Yep.</p>
	      </comment>
	    <p>Another paragraph.</p>
	  </list_item>
	</bullet_list>

I'm asking because I wanted to drop a comment in the middle of a list,
and it occurred to me that I didn't want to break the spec any more than
I wanted to break the list. What I ended up with was a little odd:

	A paragraph.
	.. A comment between two paragraphs.
	Another paragraph.
	.. A comment between a paragraph and a list.
	1. List item 1.
	.. A comment between list items 1 and 2.
	2. List item 2.
	   The second paragraph of list item 2.
	   .. A comment between two paragraphs in list item 2.
      3. List item 3.
	.. A comment between a list and a paragraph.
	The last paragraph.

List item 2 is the scorcher. To be consistent with comments between
paragraphs in column 0, comments within list items must be at the same
indent level as the paragraphs (if any) around them. That implies that
comments between list items must be at the same indent level as their
tags or bullets, hence the above.

Hmmm::

	.. this is a comment

	   this is the comment's second line

How is that rendered? One ``<comment>`` tag containing two paragraphs?
Two comment tags containing a paragraph each? One comment tag containing
three lines of CDATA of which one is blank?

Regards,
Garth.

PS: Something tells me I'm going to have a lot of fun writing test
cases. :/