Ordered list syntax.

John Gruber gruber at fedora.net
Tue Dec 30 12:00:49 EST 2003


First item on the agenda. Ordered list syntax. Feel free to comment
at will.

The obvious and intuitive syntax is "digit-dot":

1.  First
2.  Second
3.  Third

This is in fact the syntax I've been using since Markdown's
inception. The downside, however, is that in rare circumstances,
it's conceivable that someone could make a list inadvertantly. E.g.:

    You know what was a good year?
    
    1984. That was a good year.

That second paragraph will be turned into a list.

You might say, "only allow lists to start with '1.'," but that's no
good. It doesn't work at the moment, but eventually you'll be able
to start lists in Markdown starting at arbitrary numbers.

Also, you'll soon be able to create lists using letters instead of
numbers:

A. First
B. Second
C. Third
D. Etc.

For the last week, I've switched to digit-paren notation:

1)  First
2)  Second
3)  Third

This solves the problem of making the list-item delimiter something
that might occur naturally. And it doesn't look *too* bad.

But, in my opinion, it doesn't look too good either. And I find it
harder to type. And if your text editor beeps or flashes or whatever
when you type unbalanced parens, it's slightly annoying.

I've been thinking about this problem a lot. I think it's an issue
of striking the right balance between *intuitive* and *safe* syntax.
The very safest syntax -- something that's never ever going to
collide accidentally -- is going to be ugly. And but sometimes the
most intuitive syntax isn't possible to safely parse.

I think I've been veering a bit too far toward safe with my last few
syntactical decisions.

What I'm thinking is that I could go back to the original ol syntax
-- digit-dot -- and but if you really want to start a regular
paragraph with "\d+\.", you'll need to do something to escape the
period:

    1984\. What a great year.

    1984 . Use an extra space.

Sure, it's ugly. Sure, most people aren't going to know they have to
do this. And if they run into it, they're not going to realize
there's a problem until they publish their post.

But I think this might be a reasonable price to pay for the most
comfortable list syntax.

The other thing I might be able to do is only start an ordered list
if there are two or more consecutive looking-like-a-list-item
paragraphs. That'd probably solve all these problems and make this
entire message moot.

-J.G.


More information about the Markdown-discuss mailing list