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

[Brett g P. <bgp...@ac...>]

----- Original Message -----
From: "David Goodger" <go...@us...>
To: "Brett g Porter" <bgp...@ac...>;
<doc...@li...>
Sent: Tuesday, October 29, 2002 7:55 PM
Subject: Re: [Docutils-users] problems with .. include:: ?


> Brett g Porter wrote:
> > I'm really enjoying Restructured Text.
>
> Glad to hear it!  (No space though: reStructuredText.)

Sorry -- as someone who insists that the world honor my request to lowercase
my middle initial, I guarantee that I'll get it right from now on.

> > 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.
>
...that's why I put the transitions in -- I found that sequential "include"s
with no intervening text stopped all the processing and (through guessing
and blind luck) that putting transitions inbetween stopped the complaints.
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. Kudos again on building a system that let me
get as far as I did in a few hours!

BgP