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

[Dmitry Jemerov]

Hello David,

Saturday, August 10, 2002, 8:37:22 AM, you wrote:

>>> In the spec/notes.txt file there is this idea for a "sectnum"
>>> directive:
>>>
>>>     _`parts.sectnum` (automatic section numbering; add support to
>>>     the "contents" directive; could be cmdline option also)
>>>
>>> By this I'm thinking of an option to automatically number sections;
>>> the user wouldn't have to write or maintain the numbering.  Would
>>> that be a better solution for you?
>> 
>> How exactly would that look and work? Automatic section numbering
>> would be a good thing for me.

DG> Something like this::

DG>     .. sectnum::

DG>     Section One
DG>     ===========

DG>     Section Two
DG>     ===========

DG>     Subsection One
DG>     --------------

DG> When processed, the numbers "1", "2", and "2.1" would be prefixed to
DG> the titles automatically.  The directive name could be "sectnum" or
DG> "section-numbers" or "section-numbering", perhaps with a ":global:"
DG> attribute.

  OK. Docutils is still quite new to me, and I didn't understand at
once that sectnum will be a global transform specified once in the
document, and not in every section title.

  And after all, document transforms seemed easier to figure out than
list parsing code, and so the patch implementing the sectnum directive
is now at:

  http://sourceforge.net/tracker/index.php?func=detail&aid=593461&group_id=38414&atid=422032

  The directive doesn't have any attributes (should there be any?
which?). Also, the auto-generated numbers are not added to the section
IDs, and only to the title text visible in the document. A test-case
is included with the patch.

  Please review the code and check it in if you consider it worthy.
I don't give up on correct list parsing yet - I'll try to solve the
list parsing problem tomorrow.

DG> On a related note, in a 2001-07-10 post to Doc-SIG, I wrote:

DG>     I'm also toying with the idea of removing leading numbers from
DG>     implicit link names, so a section titled "3. Conclusion" can be
DG>     referred to by "Conclusion_" (i.e., without the "3.").

DG> I've added it to the to-do list, but with a "?", so it's low-to-no
DG> priority.

  I could fix this too if you like. This should be consistent with
section auto-numbering, I think - either the section auto-numberer
should add the numbers to link names, or the numbers specified in link
names by the user should be removed. The second option looks
better.

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