Sorry for re-raising this thread, but I'm new to this group, just stepped
in yesterday. I *really* like ReST very much in conjuntion with epydoc for
documenting Python sources.
I strongly agree with Beni; nested lists are ugly with these blank lines:
Allow unindented, nested lists, that contain *at least two items*, e.g.:
- highest level list
- second level list, item 1
- second item of second level list ...
- wheras this is *not* a third level list
- third item of second level
There is left an ambiguity in very, **very** rare cases:
- *Every* (except the first) line of the higher level list has to start
with the *same* bullet:
- is *not*
a nested list!)
- Your (David's) example below is *not* interpreted as a nested list,
since there is only one "list item" each.
- Indeed, this would be a nested list: Look at this C comment "/*
* Hey, I'm a
* multiline C comment */" ... but now I'm a list :(
- But maybe anyway one would write: Look at this C comment
* Hey, I'm a
* multiline C comment */" ... Ok, no list!
- If you want to get a one line sublist, you still have to use
a blank line before the sub"list".
- Only one subitem
- Somehow ironic that I inserted in this list blank lines for better
readability ... ;-) In Python docstring I often don't want to use
that much space.
Regards, Frank Sonnenburg
David Goodger wrote [2003-08-13 07:03]:
> Beni Cherniavsky wrote:
> > if you ignore (or even require) indentation in lists preceded by an
> > empty line, that would otherwise be considered block quotes, you
> > should also ignore it for lists not preceded by an empty line, that
> > would otherwise be considered a definition list. Then the above
> > does mean nested lists, at the price that neither block quotes nor
> > definition bodies can conveniently be a list (must use empty
> > comments).
> There's a higher price to pay. If a sentence contains a bullet
> (hyphen, plus sign, or asterisk; with whitespace before & after), and
> the sentence happens to wrap such that the bullet ends up as the first
> character of the second or subsequent line, it would be misinterpreted
> as a list item. For example, imagine this list wrapping thus:
> - Area of a rectangle = height
> * width.
> - Area of a triangle = 0.5 * height
> * length of base.
> This example is contrived, but such cases could and would occur in
> real use. The ambiguity is too much for reStructuredText. Epytext
> acknowledges this ambiguity in its docs, and recommends escaping. Too
> high a price, IMO.
> I'm sure this has been discussed somewhere before, but I don't know
> where or when.