[Doc-SIG] numbered headings in reST

[David Goodger]

Dmitry Jemerov wrote:
> Recently I decided to use reST to write the documentation for my
> (soon to be released) project.

Our first report from Russia.  Cool.  Are you using Docutils for Russian or
English text?

> 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.

Yes, the "1." is recognized as a list marker.  I've had another similar bug
report recently; see http://docutils.sf.net/spec/notes.html#bugs (marked
with "@@@").  I'll be looking into it soon.  It may be time to re-examine
the PELI (potential enumerated list item) idea; see the block quote in
http://docutils.sf.net/spec/rst/problems.html#enumerated-list-markup .

> 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?

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?

In the meantime, you can backslash-escape the title to avoid it being
mistaken for a list marker::

      \1. This is the heading of section one
      ======================================

I know, it's ugly.

> Maybe I could try to do a patch for numbered headings support myself?

If you'd like to give it a try, please go for it!  But I think the correct
approach would be to fix the current naive parsing, rather than just allow
for special cases like numbered titles.  Fixing the enumerated list parsing
would require some lookahead, as is done with definition lists and section
headers: the first line isn't acted upon until the second line is checked.

-- 
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/