From: Brett g P. <bgp...@ac...> - 2002-10-29 22:16:52
|
Hi -- I'm really enjoying Restructured Text. I grabbed the cvs snapshot yes= terday and everything was working as documented and as expected until I star= ted dividing a very large document up into chapters and using the =2E. include:: directive to pull the chapters into the 'real' output document. Chapt= ers that are pulled in via the include directive are omitted from the gen= erated table of contents. Well, on closer examination, the very last chapter= pulled in is included, but none of the others are. For example, I've created the following 4 files a.txt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D A Restructured Text include Test =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =2E. contents:: -------------- =2E. include:: b.txt -------------- =2E. include:: c.txt -------------- =2E. include:: d.txt b.txt~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is b.txt! =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Some body text here... c.txt ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is C dot text =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D and also some body text in here! d.txt~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ D . txt reporting for duty! =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D complete with a body! end~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~` This generates the following HTML (note that only the last one appear= s in the TOC)... <?xml version=3D"1.0" encoding=3D"utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html lang=3D"en"> <head> <meta http-equiv=3D"Content-Type" content=3D"text/html; charset=3Dutf= -8" /> <meta name=3D"generator" content=3D"Docutils 0.2.7: http://docutils.sourceforge.net/" /> <title>A Restructured Text include Test</title> <link rel=3D"stylesheet" href=3D"default.css" type=3D"text/css" /> </head> <body> <div class=3D"document" id=3D"a-restructured-text-include-test"> <h1 class=3D"title">A Restructured Text include Test</h1> <div class=3D"contents topic" id=3D"contents"> <p class=3D"topic-title"><a name=3D"contents">Contents</a></p> <ul class=3D"simple"> <li><a class=3D"reference" href=3D"#d-txt-reporting-for-duty" id=3D"i= d1" name=3D"id1"> D . txt reporting for duty!</a></li> </ul> </div> <hr /> <p>text here?</p> <div class=3D"section" id=3D"this-is-b-txt"> <h1><a name=3D"this-is-b-txt">This is b.txt!</a></h1> <p>Some body text here...</p> </div> <hr /> <div class=3D"section" id=3D"this-is-c-dot-text"> <h1><a name=3D"this-is-c-dot-text">This is C dot text</a></h1> <p>and also some body text in here!</p> </div> <hr /> <div class=3D"section" id=3D"d-txt-reporting-for-duty"> <h1><a class=3D"toc-backref" href=3D"#id1" name=3D"d-txt-reporting-fo= r-duty">D . txt reporting for duty!</a></h1> <p>complete with a body!</p> </div> </div> </body> </html> 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? -- // Today's Oblique Strategy (=A9 Brian Eno/Peter Schmidt): // Ask your body // Brett g Porter * BgP...@ac... // http://mywebpages.comcast.net/bgporter/ |
From: David G. <go...@us...> - 2002-10-30 00:55:33
|
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/ |
From: Brett g P. <bgp...@ac...> - 2002-10-30 02:00:08
|
----- 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 |
From: David G. <go...@us...> - 2002-10-31 02:46:26
|
[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/ |