Re: [Doc-SIG] numbered headings in reST
Dmitry Jemerov <email@example.com>
Mon, 12 Aug 2002 00:03:11 +0400
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?
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
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> Raises an exception with path processing on GNU/Linux (but only
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.