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

[Edward D. Loper]

> >   - 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.

Yes.  (currently a warning in my parser -- asks you to add a blank line)

> >   xxx xx xx xxx         (one paragraph or a paragraph
> >   - xx x xxxxxx          followed by a list item?)
> 
> One paragraph, with warning.

Yes.  (currently a warning in my parser -- asks you to re-word wrap
the paragraph, or to separate & indent if you intended to start a list)

> >   - 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.

Yes.  (currently a warning in my parser -- asks you to re-word wrap
the paragraph, or to add a blank line if you intended to start a 
sublist)

> >   - 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).

Yes.  And if the 2 bullets are of different types, it's a warning,
because lists should be separated by blank lines.

> > 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.

Yes.

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

In theory, someone could read the following as a single list item,
even though our rules say its two::

    1. I like the number e.  This number is approximately equal to
    2.71828182846.  But it's irrational, so that's an approximation.

Similarly with something like::

    - To find the result, simply take C{x
    - y}.

or even::

    - I like numbers that are prime, like
    2.  I also like odd numbers.

But I would argue that these are so hard to read, that we can basically
ignore them..

Note that when I say "ambiguous," I don't mean ambiguous according to
the markup language rules.. I mean that it seems possible that someone
would read it one way or the other, given that they don't know the
rules of the markup language.  It's also related to the question of
whether it's possible to make <pick-your-favorite-editor>'s word-wrapping
work properly with the formatted documentation strings.

> (ie, I agree; I *don't* disagree ;).
Good.  Does anyone else disagree, or can we tentatively move on? :)

-Edward