[Doc-SIG] simple use of docutils

[Moore, Paul]

From: David Goodger [mailto:goodger@users.sourceforge.net]
> When you combine all the features Docutils needs from its I/O,
> I'm not convinced that doing it piecemeal is better:
>=20
> * Multiple input sources: single files, directory trees, Python
>   packages, strings.
>=20
> * Multiple output destinations: single files, directory trees,
>   strings.
>=20
> * Transforms (& maybe command-line options) associated with the
>   source/destination type.  For example, a "split a monolithic
>   document tree into multiple doctrees" transform for the directory
>   tree output destination.  This is something we're currently
>   discussing on the docutils-develop list.
>=20
> * Encoding support.

Actually, I can imagine applications where I'd like all these features =
in general file I/O. Instead of writing docutils-specific classes, a =
better approach would be to write file-object wrappers.

Example::

    from fileutils import tee, transform

    f =3D open("myoutput", "w")
    f =3D tee(open("outputcopy", "w"), f)
    f =3D transform(my_function, f)

    # Now just write to f...

You could write some great pipeline-style code in there...

I think this is somewhere where restricting the code to docutils is a =
mistake. (For an example of a similar situation, distutils has a =
fancy_getopt() which is almost unknown outside of that package - this is =
in spite of the fact that it is just a getopt utility, with nothing =
distutils-specific about it...)

If there are good utilities that docutils needs, but which are not =
docutils-specific, let's package them independently so that the next =
person doesn't reinvent the wheel.

Paul.