Re: [Docutils-develop] reST Includes

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

Dethe Elza wrote:
> I'm interested in building reST documents out of smaller documents,
> so I'm looking at adding a directive for recursive inclusion.  I've
> got a couple of questions going in.
> 
> 1. Is a directive the right way to go for this?

I think so.  The only other way would be to construct a custom front
end which knows how to join the subdocuments together, but that's a
lot of work for the simple case.

> 2. Any comments on the following syntax?
> 
> .. include:: path/subdocument.rst
>    :parse: true | false (default: true)

Looks fine.  What does the "parse" attribute mean?

Here's my thinking to date, from the to-do list
(http://docutils.sf.net/spec/notes.html#misc-include):

    _`misc.include`: ``#include`` one file in another.  But how to
    parse wrt sections, reference names, conflicts?  Parse it in the
    current document's context (C-preprocessor semantics), or
    separately and then merge?

    Use C-preprocessor semantics for locating include files?  E.g.,
    ``.. include:: file.txt`` will read another file into the current
    one, relative to the current file's directory, and ``.. include::
    <standard>`` will read a standard include file from
    ``docutils/include/``.  (Should "quotes" be required around
    non-standard include files?)

Many questions to answer.

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