[Doc-SIG] lists & blank lines (was re: backslashing)

[Goodger, David]

[Edward D. Loper]
> > > The way my markup language currently works,
> > > we don't have to worry about how to detect when a new list item
> > > starts, because list item contents are required to be indented::
> > >
> > >   - this is a valid list
> > >     item.
> > >
> > >   - This is not a valid
> > >   list item.

[me]
> > Explicit wins the day. For list items, blank line & indentation
> > ambiguity will bite us all someday, so removing ambiguity is good.

[Edward]
> Um.. I'm not sure whether that means you're agreeing with me or
> disagreeing.

Agreeing. Remove ambiguity. Require blank lines & intentation to make lists
explicit.

> But the basic reasoning here was that there are
> a number of structural forms that are "ambiguous", in the sense 
> that people use them to convey different structures.. For lists,
> the "ambiguous" structures that I thought of are:
> 
>   - xxxx x xxxx         (one list item or a list item
>   xx xx x xxxxx          followed by a paragraph?)

Item followed by paragraph, with warning. Or error.

>   xxx xx xx xxx         (one paragraph or a paragraph
>   - xx x xxxxxx          followed by a list item?)

One paragraph, with warning.

>   - xx x x xxxx         (a list item with one para or with
>     - x xxxxx x          one para and one sublist?)

One para, no sublist, with warning.

>   - xx xx x xxx         (one list item with a dash in its
>   - x xx xx x x          para or two list items?)

Two list items (assuming the list was started properly, of course).

> The problem is that people will decide which choice to read
> something as based on the text.

> The solution?  Make all "ambigous" structures give either errors
> or warnings, and ask people to write them in unambiguous ways.

Yes.

> This also makes it clear whether:
> 
>   - xx xx x xxx
> 
>   xx x xx xxx x
> 
> is a list item with one para followed by a paragraph, or a list
> item with two paragraphs.

The former.

> The only ambiguity that this dosn't deal with is the last one I
> listed.

Which one was that? Unclear.

> If you disagree, we could require blank lines between list items.

Unnecessary (ie, I agree; I *don't* disagree ;). We don't need blank lines
between items if the rules for list item indentation are explicit. Blank
lines were required by StructuredText because it makes parsing easy, but
there were many complaints about wasted vertical space. These rules make an
unambiguous solution.

/DG