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. :/
on 2001-07-20 2:07 AM, Garth Kidd (garth@netapp.com) wrote:
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>
In the DTD, <comment> contains only #PCDATA. The entire comment block is treated as a text blob. None of it is processed further. I'll add mention of this to the spec. The above example would actually turn into the following (pretty-printed):: <p>A paragraph.</p> <comment> A comment with two paragraphs. Yep. </comment> <p>Another paragraph.</p>
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.
Except lists cannot contain comments; they contain only list items. List *items* can contain comments. I was wrestling with exactly this issue the other day. In SGML, we could always use an inclusion exception:: <!ELEMENT document - - (%document.model;) +(comment)> (If my SGML isn't too rusty ;-) But those are dangerous and unwieldy at the best of times. I used an XML DTD to specify the document model, and so far it's working out well. Shortcomings, like not being able to have comments just anywhere, are annoying at first. But in hindsight these "shortcomings" almost invariably turn out to be the only sane way to do it.
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?
No to both.
One comment tag containing three lines of CDATA of which one is blank?
Yes.
PS: Something tells me I'm going to have a lot of fun writing test cases. :/
Unit testing is *definitely* the way to go. And fun too. -- David Goodger dgoodger@bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sf.net - reStructuredText: http://structuredtext.sf.net - The Go Tools Project: http://gotools.sf.net
Except lists cannot contain comments; they contain only list items.
Hmmm. :: 1. List item. 2. Another. .. Guys, should we remove this one? It's angry. 3. Angry. 4. Fnee. I just ended up with two lists, didn't I? :)
List *items* can contain comments.
Cool. I can think of circumstances for which people will want to use comments to dedent. Undent? Oh, I give up. :)
PS: Something tells me I'm going to have a lot of fun writing test cases. :/
Unit testing is *definitely* the way to go. And fun too.
Already submitted a patch with more tests. :) Regards, Garth.
participants (3)
-
David Goodger -
Garth Kidd -
Garth T Kidd