Re: [Docutils-develop] reST Includes

[Dethe E. <de...@ma...>]

On Fri, 2002-08-16 at 13:04, David Goodger wrote:
> Thanks for your comments.  How about sharing them with docutils-develop?

Oops!  I meant to do that, but forgot that this list doesn't reply to
list by default.  Here's my earlier response:

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

OK, cool.

> > 2. Any comments on the following syntax?
> > 
> > .. include:: path/subdocument.rst
> >    :parse: true | false (default: true)
> 
> Looks fine.  What does the "parse" attribute mean?

parse = true
  Treat the included text as reST and parse as part of the document

parse = false
  Treat the included text as literal text (maybe it's already HTML or
whatever) and just insert it.

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

Treat it all as one document unless notified otherwise?  I think that's
reasonable default behaviour.  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.

So now the directive would look like:

.. include:: path/subdocument.rst
   :parse: true | false (default: true)
   :same-context: true | false (default: true)


>     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?)

Umm.  I don't see a lot of value in using "standard" include locations. 
URI are better: Include off the net, include from a file, include from a
relative path...

--Dethe