Re[2]: [Doc-SIG] numbered headings in reST
Dmitry Jemerov
Dmitry Jemerov <yole@yole.ru>
Fri, 9 Aug 2002 19:47:05 +0400
Hello David,
Friday, August 9, 2002, 5:02:30 AM, you wrote:
>> Recently I decided to use reST to write the documentation for my
>> (soon to be released) project.
DG> Our first report from Russia. Cool. Are you using Docutils for Russian or
DG> English text?
English for now, but a Russian translation is planned for a later
time.
>> One of the first things I tried to write in my file was:
>>
>> 1. This is the heading of section one
>> =====================================
>>
>> However, this doesn't work, and the following error message is
>> given:
>>
>> WARNING (level 2 system message)
>> Enumerated list ends without a blank line; unexpected unindent at line 5.
DG> Yes, the "1." is recognized as a list marker. I've had another similar bug
DG> report recently; see http://docutils.sf.net/spec/notes.html#bugs (marked
DG> with "@@@"). I'll be looking into it soon. It may be time to re-examine
DG> the PELI (potential enumerated list item) idea; see the block quote in
DG> http://docutils.sf.net/spec/rst/problems.html#enumerated-list-markup .
In my opinion, it is not a good idea to require multiple adjacent
list items. As far as I understand, this will cause the following not
to be treated as a list:
* List item one
Here is a long list of considerations related to the list item
one.
* List item two
And some more considerations.
What I would prefer is a different form of lookahead: if the line
following a potential list item is definitely not a list item (a
heading marker, or the start of a table, or something like that), then
the list is not created.
>> I've seen no mention of numbered headings in the spec, but in my
>> opinion, they are a very commonly used construct. Are you planning to
>> support numbered headings in the future version of DocUtils?
DG> In the spec/notes.txt file there is this idea for a "sectnum" directive:
DG> _`parts.sectnum` (automatic section numbering; add support to
DG> the "contents" directive; could be cmdline option also)
DG> By this I'm thinking of an option to automatically number sections; the user
DG> wouldn't have to write or maintain the numbering. Would that be a better
DG> solution for you?
How exactly would that look and work? Automatic section numbering would
be a good thing for me.
Another idea is to have section auto-numbering like proposed by Tony Ibbs
(alternatives.txt, Auto-Enumerated Lists, item 4):
#1. Section 1.
==============
#1.#1. This is a subsection of section 1.
-----------------------------------------
#1.#2. And another subsection
-----------------------------
This looks more readable as plaintext than embedding some directives
like _`parts.sectnum` in the section title.
DG> In the meantime, you can backslash-escape the title to avoid it being
DG> mistaken for a list marker::
DG> \1. This is the heading of section one
DG> ======================================
DG> I know, it's ugly.
OK, I'll use this if nothing else works. However, numbered headings
are common enough to require a better solution.
>> Maybe I could try to do a patch for numbered headings support myself?
DG> If you'd like to give it a try, please go for it! But I think the correct
DG> approach would be to fix the current naive parsing, rather than just allow
DG> for special cases like numbered titles. Fixing the enumerated list parsing
DG> would require some lookahead, as is done with definition lists and section
DG> headers: the first line isn't acted upon until the second line is checked.
OK, once we decide on the best solution, I'll try to do the implementation.
--
Best regards,
Dmitry mailto:yole@yole.ru