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

[Edward D. Loper]

> [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.
> 
> As is:
> 
> > >     - I like numbers that are prime, like
> > >     2.  I also like odd numbers.

But there's an important difference here.  A parser will give a
warning for the second and third examples, but won't for the
first example.  I would prefer to be able to say "if something
might be ambiguous to people, then we either issue a warning
or an error."  But in the example about liking e, that rule
doesn't hold.

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

The intention was that C{..} was used to stand for whatever colorizing
we decide we like.  In that case, I agree that it should be 2 errors
(mismatched delimiters) and possibly a warning.

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

That's been my goal so far.  But the problem is deciding what's
ambiguous...

-Edward