[Doc-SIG] numbered headings in reST
David Goodger
goodger@users.sourceforge.net
Mon, 12 Aug 2002 21:17:30 -0400
[David]
>>> To enable a different type of table of contents, the section titles
>>> should have an extra attribute, such as "auto".
[Dmitry]
>> In the version that I checked in today, that is also implemented.
[David]
> 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.
I've reworked the "sectnum" directive & transform. Here's how:
* Changed the "contents" directive to produce a "first writer"
transform. Now there's no order issues.
* Moved most of the ``docutils.parsers.rst.directives.parts.sectnum()``
docstring to the documentation:
http://docutils.sf.net/spec/rst/directives.html#automatic-section-numbering
* Reworked the ``docutils.transforms.parts.SectNum`` transform's
``update_section_numbers()`` method:
- Simplified calling the method (default parameter values).
- Removed the "autonum_origtitle" and "autonum_prefix" attributes
from "section" elements: unnecessarily redundant. Instead, the
"title" elements get an "auto" attribute.
- The section number text is inserted into the title, wrapped in a
``<generated class="sectnum">`` element. We don't actually use
this yet, but it could be used this to remove the generated text
if we need to.
* Reworked the ``docutils.transforms.parts.Contents`` transform's
``build_contents()`` method:
- It turns out that we don't need to build enumerated lists; we
continue to build bullet lists as before.
- If an "auto" attribute is detected in a title, we add a
``class="auto-toc"`` attribute to the bullet list.
- The generated text is left alone; there's no need to remove it.
* This style makes the bullets invisible::
ul.auto-toc {
list-style-type: none }
Take a look at the results:
http://docutils.sf.net/tools/test.html#table-of-contents
--
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/