[Doc-SIG] lists & blank lines (was re: backslashing)
Goodger, David
dgoodger@atsautomation.com
Mon, 16 Apr 2001 17:00:32 -0400
[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