[Doc-SIG] lightweight markup: bullets
Edward D. Loper
edloper@gradient.cis.upenn.edu
Wed, 11 Apr 2001 13:06:41 EDT
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