[Docutils-users] Re: problems with .. include:: ?

[David G. <go...@us...>]

[David]
>> From http://docutils.sf.net/spec/doctree.html#transitions:
>>
>>     A transition may not begin or end a section or document, nor
>>     may two transitions be immediately adjacent.
>>
>> The transitions were between sections (easy to see if you use the
>> tools/publish.py front end).  The parser isn't enforcing that rule,
>> which is a bug that should be fixed.

Fixed.  The parser now enforces the structure; transitions aren't
allowed at the beginning or end of sections or the document itself.

>> Removing the transitions turns up a much more serious bug though,
>> generating a traceback.  *This* could be an "include" directive
>> bug.  I'll look into it.

[Brett]
> ...that's why I put the transitions in -- I found that sequential
> "include"s with no intervening text stopped all the processing

You should have reported *that* as a bug! ;)

> putting transitions inbetween stopped the complaints.

That will work as a temporary work-around, until the "include"
directive problem is fixed.  I don't know *why* it works (or why it's
needed) yet.

It turns out that part the problem is quite deep.  The "include"
directive starts a nested parse, which means that a section in the
included file must be complete (it can't start in the included file
and finish in the master file).  This isn't very useful, so the
implementation of the "include" directive has to be rethought.
Unfortunately, to fix "include" it may be necessary to rework a very
low-level aspect of the parser.  If you're interested, I'll be
following up on this on the docutils-develop list
(http://lists.sf.net/lists/listinfo/docutils-develop).

> Unfortunately I've been in the position of needing to convert an
> existing doc over to reStructuredText in a hurry, and haven't had
> much time to study the spec or the code closely.

Understandable :)

> Kudos again on building a system that let me get as far as I did in
> a few hours!

Thanks.

-- 
David Goodger  <go...@us...>  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/