[Doc-SIG] numbered headings in reST

[David Goodger]

[David]
>> Perhaps there should be some way to control the enumeration
>> sequences? For example, in a long document chapters are usually
>> numbered, but appendices use letters (A, B, C, ...).  Perhaps
>> multiple "sectnum" directives could exist, each specifying the
>> style of the remainder of the document.  So just before the first
>> appendix, there could be a ".. sectnum:: :enum: A" directive.
>> Should this apply only to the first part of the section number, or
>> should each part be adjustable?  Of course, this doesn't have to be
>> implemented now; we can add it to the to-do list until someone
>> actually needs it.

[Dmitry]
> This is also a good idea, and I'd like to implement it soon. I think
> that it's enough to configure only the first part of the number;
> I don't see a clear syntax that will allow configuring all parts.
> After all, if some non-trivial numbering is needed, one could just
> write the numbers by hand.

Fair enough.  If you implement it, I think the attribute should be
called "start", not "enum".  It will specify the sequence set to use
at the same time as the starting value.  For example::

    .. sectnum: :start: 1
    
    .. sectnum: :start: A
    
    .. sectnum: :start: 5
    
    .. sectnum: :start: I

The first one is the default: start at 1, numbered.  The second one
specifies letters, and start at "A".  The third specifies numbers,
start at 5.  The last example could signal Roman numerals, although I
don't know if they'd be applicable here.  Enumerated lists already do
all this; perhaps that code could be reused.

Here comes the tricky part.  I'd expect to be able to use the
"sectnum" directive multiple times in a single document.  For example,
in a long document with "chapter" and "appendix" sections, there's be
a second "sectnum" before the first appendix, changing the sequence
used (from 1,2,3... to A,B,C...).  This is where the "local" concept
comes in.  This part of the implementation can be left for later.

>> The second issue is the interaction of "sectnum" with the
>> "contents" directive.  Try processing a document with both
>> directives; the order of the directives is significant.  If the
>> "contents" directive comes before "sectnum", the section numbers
>> are not reflected in the table of contents.  If "sectnum" comes
>> first, the section number do make it to the table of contents.
>> I've put examples on the web:
>>
>> - "contents" first: http://docutils.sourceforge.net/tools/test1.html
>> - "sectnum" first: http://docutils.sourceforge.net/tools/test2.html
>>
>> The reason for this is because the "sectnum" directive inserts a
>> ``pending`` element, which is fine.  The "contents" directive does
>> too.  Both are labeled "last reader", meaning they're both
>> triggered after the standard reader transforms are finished; a
>> simple scheduling mechanism.  But within "last reader", it's first
>> come, first served. Should we leave the behavior dependent on the
>> order of directives, or choose one and enforce it?  It would be
>> easy to enforce either order by labeling one of the ``pending``
>> elements as "first writer" instead of "last reader".
> 
> Well, now the directives are coupled even more, and so there must be
> a way to enforce correct processing order, and not make it the
> user's responsibility.

Agreed.  I think changing "contents" to a "first writer" transform
would be fine for now.  That way, "sectnum" always happens first.

> Also, the "sectnum" directive has another dependency: it must run
> after the DocTitle transform. This works correctly now, but maybe it
> should somehow be made explicit.
> 
> What do you think of introducing a numeric priority system for
> pending operations? Is this over-design? I think that we may
> encounter more cases of transform order dependencies later, and the
> current four-level system may not be enough.

I thought about a priority system too.  I think it's too early to say.
We don't quite need it yet, so let's hold off until we do.  I'll add
it to the to-do list though.  For now, documentation should be enough.

>> It's clear that the ``pending`` elements need to be documented:
>> what they're used for and when they're triggered ("first reader",
>> "last writer", etc.).
> 
> Frankly speaking, I still haven't found the code that triggers
> the "pending" elements and handles all the "first reader" stuff. :-)
> So I'd appreciate more documentation on that issue very much.

It's in ``docutils/transforms/universal.py``, from the ``Pending``
class to the end.  ``docutils.nodes.pending`` explains how the
``pending`` node works; I'll add some cross-references.

>> Notice the table of contents in the test2.html document.  Currently
>> it looks something like this::
>>
>>     * 1. Structural Elements
>>       - 1.1. Section Title
>>       - 1.2. Transitions
>>     * 2. Body Elements
>>       - 2.1. Paragraphs
>>
>> I think it should look like this (perhaps with extra indentation)::
>>
>>     1. Structural Elements
>>     1.1. Section Title
>>     1.2. Transitions
>>     2. Body Elements
>>     2.1. Paragraphs
>>
>> An alternative could look like this::
>>
>>     1. Structural Elements
>>        1. Section Title
>>        2. Transitions
>>     2. Body Elements
>>        1. Paragraphs
>>
>> To enable a different type of table of contents, the section titles
>> should have an extra attribute, such as "auto".
> 
> In the version that I checked in today, that is also implemented.

I see that.  It's not exactly what I had in mind though.  It will be
easier for me to fix it than explain what I mean, so I'll handle it.

> I haven't found a DTD element that would be formatted as a plain
> list of strings with no paragraph breaks between them. ...
> Therefore, the contents for auto-numbered sections is now generated
> as an enumerated list.

I think the current bullet list structure is adequate; what's
necessary is some context recognition in the writer.

> This looks pretty nice, with one exception: the HTML writer doesn't
> support prefixes for enumerated lists. Thus, the table of contents
> in HTML looks as your second alternative, and not the first one
> (which is what I would like to achieve).
>
> Do you have any ideas on implementing the prefixes for enumerated
> lists in HTML? I would really like to have this fixed.

CSS2 might be able to handle that, but I don't think we need to go
that route.  Simpler is better, especially since CSS2 support is
spotty.  Adding some more smarts to the HTML writer should solve it.
I'll take care of this also.

-- 
David Goodger  <goodger@users.sourceforge.net>  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/