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

[Goodger, David]

[Edward D. Loper]
> 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.

I'd say this is just another example of:

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

As is:

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

This one is two bulleted items:

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

(Unless the C{} syntax is used, in which case it's a single malformed item
[second line should be indented] or an item followed by a paragraph [should
be a blank line, and "C{x" should trigger an error]. In any case, it
warrants a warning.)

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

Humans can parse text much more flexibly than software. Make the software
(markup rules) quite strict, so that a text passing through the software
without errors or warnings has no chance for ambiguity at the human-level.
The best you can do is make the software say, "I don't understand what you
mean here." Timbot's rule 12: "In the face of ambiguity, refuse the
temptation to guess."

/DG