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