[Doc-SIG] Including files

[Pearu Peterson]

Hi,

I am using Docutils in creating a reference manual (for F2PY project) and
found that it would be nice if rst formatted text files could have some
support for including other rst formatted text files as well as various
source codes to the document. The equivalent hooks in LaTeX would be 
\input{..} and \verbatiminput{..} commands.

Typical usage cases:

* If a rst-text file tends to become very large (in the sense that
  its printed version has, say, 20 or more pages) then factoring it to
  different files would ease maintaining such documents.

* Including example source codes. Currently one has to maintain two copies
  of source codes, one as a source file and one typed (copied) into
  the rst-text file.

I am not sure what would be appropiate Docutils hooks for emulating
LaTeX \input or \verbatiminput commands but may be something like the
following:

* Using

  ::

    .. input:: filename

  in a rst-text file is equivalent to a situation as if 
  the ``.. input:: filename`` part is replaced by the contents of
  ``filename``, possibly taking into account also indentation level.
  Possible variations for ``input``::

    file
    insert
    include
    fileinput
    ..

* Using

  ::

    .. verbatim:: filename
 
  is equivalent to including the contents of ``filename`` as a literate
  block to the current rst-text file.
  Possible variations for ``verbatim``::

    source
    verbatiminput
    ..

What do you think?

Pearu