[Doc-SIG] Auto-Numbered Enumerated Lists (reStructuredText)

David Goodger goodger@users.sourceforge.net
Mon, 29 Apr 2002 23:31:48 -0400


Tony J Ibbs (Tibs) wrote:
> Another alternative for auto-numbered lists, sort-of similar to the
> way we handle footnotes at the moment, is to allow::
> 
>    #1. First item.
>    #3. Aha - I edited this in later.
>    #2. Second item.

I've added this as syntax alternative 4.

> This requires the user to ensure that list items are still unique -
> probably a good thing

That doesn't seem like a good thing to me.  We'd get the ugly syntax
of the first two alternatives plus the inconvenience of having to
account for item numbers, without much convenience gain (just random
ordering).

It might fly if we modify this proposal like so:

- Simply prepend a "#" to a standard list enumerator to indicate
  auto-enumeration.

- The numbers (or letters) of the enumerators themselves are not
  significant, except:

  - as a sequence indicator (arabic, roman, alphabetic),

  - and perhaps as start value (first list item)

> I would suggest that it *not* be possible to have two adjacent lists
> with this mechanism

It'll happen though.  A system message (warning or error) would be
generated; I assume that's what you mean.

> so the problems David describes with the list::
> 
>        1. Item 1.
> 
>        1. Unintentional duplicate of item 1.
> 
>        2. Item 2.
> 
> would not be allowed

Actually, there are no "problems" with this in the current
spec/parser.  It results in two lists, "1" and "1,2".  Were the blank
lines to be omitted between items, a warning would be generated
between the two lists.  Under Fred's proposed semantics, the list
would be parsed as "1,2" and "2".

> As a side-effect, would we then allow people to assume that such
> items could be referred to?

That would be tricky, and going too far I think.  Either all
auto-numbered lists in a document would need to have unique labels, or
some sort of scoping rules would be required: would a list item
reference refer to the preceding list or the following list?  I'm
loathe to introduce such rules.  A preferable solution would be to use
the existing hyperlink constructs to refer to the body of a list item;
the item number couldn't be transferred, but a live link could be
created.

Auto-enumerated lists are only a marginal convenience feature; the
syntax and semantics should be simple and clean.  Too complex and it's
no longer convenient enough to justify its existence.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
  - The Go Tools Project: http://gotools.sourceforge.net/