[Doc-SIG] Re: Comments within lists

[David Goodger]

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