[Doc-SIG] docutils status report

[Tony J Ibbs (Tibs)]

Edward Welbourne wrote:
> But not as slowly as LSL's tools update program ...

Ooh - cutting! At least we did upgrade eventually (and both Bill and
Graham were quite enthusiastic about it). Some day we'll have to
consider 2.0...

> >         ' -- ' -- This is an awkward case
> but, for all that, a necessary one.

Well, yes.

It is also easy enough to do with regular expressions - one just makes
the descriptive case allow the literal markup case to occur in its title
(and, of course, finds lists before markup!)

> Meanwhile, consider (e.g.) a function whose docstring lists
> the ways a line can start a list item, in which one might say:
>
>    1. -- ordered list (using arabic numerals)
...etc...
> which, clearly, I want to see as a description list, not a
> very confused ordered list.  Will that work ?

That will work because descriptive lists are (very deliberately) looked
for before the other sorts of list, to cope with exactly that sort of
point.

> and can I use `1)' and `a)' instead of
> `1.' and `a.' ? (as lead-in to list items)

No. Not for any greatly fundamental reason, but because it's not in the
original definition(s) of ST[NG]. This is the sort of thing people could
ask for as an "enhancement" - I can't (off the top of my head, and with
no great depth of thought) see why it shouldn't be able to work.

(There are, of course, classes of things one *can't* do with
ST<variants> - not least because they use symmetrical start/end tags.
But the system is surprisingly flexible.)

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)