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

[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.
> 
> Explicit wins the day. For list items, blank line & indentation
> ambiguity will bite us all someday, so removing ambiguity is good.

Um.. I'm not sure whether that means you're agreeing with me or
disagreeing..  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?)

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

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

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

(where "-" represents any bullet charcter, and "xxx" is text.)

The problem is that people will decide which choice to read
something as based on the text..  Which will lead to errors
in writing formatted docstrings.

The solution?  Make all "ambigous" structures give either errors
or warnings, and ask people to write them in unambiguous ways.
To make any of them look like singe paras, simply re-word-wrap
so that the "-" is not at the beginning of the line.  To make
them look like list items, indent list items and separate them
with blank lines; and indent the contents of list items.  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 only ambiguity that this dosn't deal with is the last one I
listed.  But I decided that we could probably ignore that ambiguity,
because if anyone *does* try to make it one paragraph with an embedded
bullet, it's unreadable anyway:

    1. This is a list
    2. This list item talks about the number
    1.  1. is a good number.
    3. That was confusing.

If you disagree, we could require blank lines between list items.  The
main disadvantage there is that it would add a fair amount of blank
space (fields obey the same rules as lists, so you'd have to say::

    @param x: ...

    @param y: ...

    @returns: ...

    @raises: ...

instead of::

    @param x: ...
    @param y: ...
    @returns: ...
    @raises: ...

)

The other advantage of this set of rules is that it allows us to
completely separate colorizing from structuring..  Which means that we
can temporarily put colorizing aside, and concentrate on what we want
our structuring rules to do.

-Edward