[Doc-SIG] lightweight markup: bullets
Edward D. Loper
edloper@gradient.cis.upenn.edu
Fri, 13 Apr 2001 15:47:33 EDT
Tim Peters said:
> [Edward D. Loper, on L<...> for list items]
> > Perhaps. The reason that I didn't do that is that the use of <...> or
> > L<...> for bullets is really very different from the use of X<...> for
> > coloring.
>
> It's barely different at all to me: it's markup, as opposed to not markup,
> and that's the *primary* distinction that needs to be learned. You
> overburden my biological pattern-recognition engine if I have to learn N
> different lexical conventions for N different categories of markup.
Well, I guess that part of the idea behind a lightweight markup is that
we should try to re-use regexps that are already in your brain. Which
might be a good argument with just sticking with lists that look like:
- list item
- another list item
or:
1. list item
2. another list item
> I've got no particular use for list markup at all,
What markup do you find that you do have use for (while writing
docstrings)? I personally tend to just use C{code} regions (for
identifiers, mainly); unordered lists; and literal blocks/doctest
blocks. Oh, and fields for specifying info about specific parameters
or the return value or what exceptions are thrown, etc.
-Edward