Re: [Docutils-users] StructuredText's ordered list

[David G. <go...@us...>]

Mark McEahern wrote:
> Forgive me if this is a FAQ.

Well, since up to now there hasn't *been* an official FAQ, you're
forgiven. ;-)

> In StructuredText, you can do:
> 
>   1.  a
> 
>   1.  b
> 
>   1.  c
> 
> and you'll get an ordered list (<ol><li>a</li><li>b</li><li>c</li>).
> The advantage of this approach is that I don't need to manage the
> numbers (e.g., if I move c between a and b, I don't have to
> "renumber" them).
> 
> With reStructuredText, OTOH, the above generates three ordered
> lists:

... omitted ...

> There's probably a good reason for this.  I realize this is part of
> the specification:
> 
> http://docutils.sf.net/spec/rst/reStructuredText.html#enumerated-lists
> 
> Any insight on why the implicit sequence approach is avoided (which
> seems usable at least in isolation) is greatly appreciated.

There's a discussion here:

  http://docutils.sf.net/spec/rst/alternatives.html#auto-enumerated-lists

It's lingering there, awaiting a champion.  I introduced a
colleague to Docutils recently, let him loose, and his first
suggestion was exactly this extension; the evidence is mounting that
this would be a good change.  I'm partial to alternative 2, since it
establishes the enumeration sequence (arabic numerals, letters, etc.),
and reduces the "line noise".

> Perhaps the answer is simply:
> 
>   Explicit is better than implicit.

That's a big part of it!  I put auto-enumerated lists on to the to-do
list (with a "?"), so it won't be forgotten, but it's not my priority
right now.  If you're interested, patches are gratefully accepted!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/