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

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

Brett g Porter wrote:
> I'm really enjoying Restructured Text.

Glad to hear it!  (No space though: reStructuredText.)

> I grabbed the cvs snapshot yesterday
> and everything was working as documented and as expected until I started
> dividing a very large document up into chapters and using the
> .. include::
> 
> directive to pull the chapters into the 'real' output document. Chapters
> that are pulled in via the include directive are omitted from the generated
> table of contents. Well, on closer examination, the very last chapter pulled
> in is included, but none of the others are.

That actually had nothing to do with the "include" directive.  It was
because of the transitions (lines of dashes in a.txt) between sections.  The
table of contents is compiled in reverse from the end of the document,
stopping at the first non-section; in this case a transition.  Thus only the
last section got in.

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

> Is this a known limitation? Something that will be fixed? Or is this one of
> those "push up your sleeves and fix it, pal" things?

Not a known problem until now; thanks for the bug report.  It ought to be
fixed at some point, when someone considers it important enought to fix.  If
it's important to *you*, you should definitely attempt a fix or at least a
diagnosis.  Bug-fix patches are *always* welcome!  The docutils-develop list
is the best place to discuss bugs in the code.

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