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

[Dmitry Jemerov]

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