[Doc-SIG] lightweight markup: bullets

[Edward D. Loper]

So I'm still playing around with developing a lightweight markup
language for docstrings, and wanted to bounce an idea off the
list..

Background
==========

Traditionally, there has been some difficulty in deciding how
to do lightweight lists.  The simplest idea is to do something
like::

  - this is a list item
  - this is another list item
  - This is a multiline
    list item.

Where list items are lines that start with a bullet character.

But then there's an issue of whether that makes it safe to include
dashes (surrounded by spaces) in paragraphs.. because they could get
word-wrapped such that the dash appears at the beginning of the line,
which would then make it into a list item.  So a paragraph containing
the sentence::

    This is a paragraph - it contains a dash.

Might get word-wrapped at some point to::

    This is a paragraph
    - it contains a dash.

The problem also applies to ordered lists: the paragraph::

    Some people like the number 1.  Some don't.

Might get word-wrapped to::

    Some people like the number
    1.  Some don't.

There are some ways to get around this *most* of the time with
indentation (by requiring that lists be indented), but they don't work
all of the time.  For example, with a paragraph like::

    return: Some real number that's greater than
        1. The number should also be less than
        2. ...

it doesn't help, because there's no way to tell whether that's a list
item or part of the first paragraph..

My Question
===========

So the approach that I wanted to get peoples' opinion on is using
bullets that look like::

    <-> This is an unordered list item.
    <1> This is an ordered list item.
    <foo> This is a description list item.

Here, I'm assuming that we're already using C<...> etc. to delimit
colored regions, so <...> without a letter before it should never
appear in a paragraph.  (Alternatively, replace '<' with '{' and '>'
with '}'.  I've been going back and forth on which one I like better.)

The advantages of this approach are:
    - it's consistant between list types
    - it's very easy to detect (for coloring, etc.)
    - it's safe with respect to word-wrapping paragraphs
    - it easily allows for a wide variety of bullets (e.g., 
      for description list items)

The main disadvantage that I see is:
    - It's uglier than just using '-' or '1.'.

Is it too ugly?  Do you see any other problems with it?  Do you have
any better ideas?

-Edward