Re: [Docutils-develop] reST Includes

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

Dethe Elza wrote:
>>> There could be another flag on the include directive, as there is
>>> in the recursive parse within reST I believe, telling it whether
>>> to process the included text within the same context or not, but I
>>> think the default should be to assume the same context.
>> 
>> What "recursive parse within reST" are you talking about?
> 
> Ummm.  There was something somewhere in the code.  I can't remember
> exactly where and I don't have a chance to dig it out right now.  I
> could be wrong.  Your mileage may vary.  Void where prohibited.

There *is* plenty of recursive parsing going on.  I just wasn't sure
which one you meant.  Not to worry.

>> Factoring in the above, we get::
>> 
>>     .. include:: path/subdocument.rst
>>        :raw: (true if set)
> 
> Looks good.
> 
>> That's feasible.  I wonder how to actually do the parse, though.  I
>> don't think it's a good idea to alter the already-read data, so a
>> separate, nested parse would probably be in order.  Also, the error
>> reporting mechanism would have to be revamped to include the file
>> which is the source of system messages.
> 
> Um.  I'm not sure if I'm up to revamping the error reporting
> mechanism. I'm trying to find something that's *easier* than
> 
>   cat file1.rst file2.rst file3.rst | html.py> finished.html
> 
> I think I can handle creating a directive and even writing up how to
> create a directive, but I'm not up for a revamp of the core system.

Those two would be great!  I'll be happy to take care of revamping
``utils.Reporter``.

> Is image still the best directive to get started with?

Yes, it does all the parsing you'll need.  And also look at the
directives/admonitions.py module to see how to use
``state.nested_parse()``.  If the files you're including contain
section titles (which the general case would require), you'll need to
pass in ``match_titles=1``.

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