Re[2]: [Doc-SIG] numbered headings in reST

[Dmitry Jemerov]

Hello David,

Sunday, August 11, 2002, 6:28:37 AM, you wrote:

>> A test-case is included with the patch.

DG> That's great; thank you.  How are you at documentation? ;-)

  I'll try to write the documentation after the code is finalized and
the issues are solved.

DG> The first issue is,

>> The directive doesn't have any attributes (should there be any?
>> which?).

DG> Perhaps, like with the "contents" directive, there could be a "depth"
DG> attribute?  Would it be useful to limit the depth of numbered
DG> sections?  Sections too deeply nested wouldn't be numbered.

  Yes, that's a good idea, and simple to implement, too. It's
implemented in the version of the patch that I checked in today.

DG> Also, should there be a "local" attribute?  Perhaps sections from a
DG> certain level down could have numbering enabled, where sections in the
DG> rest of the document are not numbered.  For example, a reference
DG> section of a manual might be numbered, but not the rest.  OTOH, an
DG> all-or-nothing approach would probably be enough.

  In my opinion, most documents are numbered all-or-nothing. We could
implement "local" if someone requests it.

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

  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.

DG> In any case, the directive as is doesn't do anything with its ``data``
DG> parameter.  If it doesn't accept attributes, it should signal an error
DG> if there *is* any directive data.

  Well, now the directive does accept an attribute (depth), and it
uses the standard mechanism for parsing attributes and reporting errors.
Hopefully that's good enough. :-)

DG> The second issue is the interaction of "sectnum" with the "contents"
DG> directive.  Try processing a document with both directives; the order
DG> of the directives is significant.  If the "contents" directive comes
DG> before "sectnum", the section numbers are not reflected in the table
DG> of contents.  If "sectnum" comes first, the section number do make it
DG> to the table of contents.  I've put examples on the web:

DG> - "contents" first: http://docutils.sourceforge.net/tools/test1.html
DG> - "sectnum" first: http://docutils.sourceforge.net/tools/test2.html

DG> The reason for this is because the "sectnum" directive inserts a
DG> ``pending`` element, which is fine.  The "contents" directive does
DG> too.  Both are labeled "last reader", meaning they're both triggered
DG> after the standard reader transforms are finished; a simple scheduling
DG> mechanism.  But within "last reader", it's first come, first served.
DG> Should we leave the behavior dependent on the order of directives, or
DG> choose one and enforce it?  It would be easy to enforce either order
DG> by labeling one of the ``pending`` elements as "first writer" instead
DG> 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.

  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.

DG> It's clear that the ``pending`` elements need to be documented: what
DG> they're used for and when they're triggered ("first reader", "last
DG> 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.

DG> Notice the table of contents in the test2.html document.  Currently
DG> it looks something like this::

DG>     * 1. Structural Elements
DG>       - 1.1. Section Title
DG>       - 1.2. Transitions
DG>     * 2. Body Elements
DG>       - 2.1. Paragraphs

DG> I think it should look like this (perhaps with extra indentation)::

DG>     1. Structural Elements
DG>     1.1. Section Title
DG>     1.2. Transitions
DG>     2. Body Elements
DG>     2.1. Paragraphs

DG> An alternative could look like this::

DG>     1. Structural Elements
DG>        1. Section Title
DG>        2. Transitions
DG>     2. Body Elements
DG>        1. Paragraphs

DG> To enable a different type of table of contents, the section titles
DG> should have an extra attribute, such as "auto".

  In the version that I checked in today, that is also implemented. I
haven't found a DTD element that would be formatted as a plain list of
strings with no paragraph breaks between them. (Footnotes and
citations are formatted like that, but abusing this for the table of
contents would be too much of a hack.) Therefore, the contents for
auto-numbered sections is now generated as an enumerated list.

  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.

DG> The third issue has to do with references:

>> Also, the auto-generated numbers are not added to the section IDs,
>> and only to the title text visible in the document.

DG> I think this is the correct approach.

DG> I think with the "sectnum" directive, we've got the right solution.
DG> It's independent of hyperlinks.  We'd probably have to leave both
DG> reference options open.  Fiddling with the reference names doesn't
DG> feel right to me; too much opportunity for edge-case screw-ups.

  OK, then so be it. The references will not be touched, for now.

DG> Other than that, the directive looks great!

>> Please review the code and check it in if you consider it worthy.

DG> Better yet, I'll add you as a developer and let you check it in
DG> yourself.  Let's hash out the issues raised above though.  The
DG> reference issue (third) can be ignored for now.  The table of contents
DG> interaction (second issue) must be dealt with.  And we should at least
DG> decide which attributes could be useful, and which should be tossed
DG> (first issue).

  The TOC issue is half-solved: we still need to decide if the current
way to specify pending operation priorities is sufficient. As for the
attributes: :depth: is implemented, :enum: is planned to be
implemented soon, and that's all. Right?

DG> On a related note, the small patch to test/package_unittest.py (which
DG> we discussed off-list) inspired me to finally fix this bug:

DG>     - Fix tests to run standalone.  I.e., allow::
    
DG>           cd test/test_rst
DG>           test_inline_markup.py
    
DG>       Raises an exception with path processing on GNU/Linux (but only
DG>       sometimes???).

  Well, in fact, the os.getcwd() fix was not correct - I proposed it
without actual testing. The version I checked in today has a different
fix, with some comments added - hope it works fine.

-- 
Best regards,
 Dmitry                            mailto:yole@yole.ru