[Doc-SIG] simple use of docutils
David Goodger
goodger@users.sourceforge.net
Fri, 18 Oct 2002 19:53:17 -0400
Michael Hudson wrote:
>> * Multiple input sources: single files, directory trees, Python
>> packages, strings.
>
> What's the interface going to be for these? Here's a suggestion: a
> file-like object or something you can iterate over to get file-like
> objects. That covers all the above rather easily.
I'm not sure what the interface will be; haven't got there yet.
Suggestion noted.
>> * Multiple output destinations: single files, directory trees,
>> strings.
>
> single files & strings are easily handled by file-like objects.
> What interface do you suggest for outputting to multiple files?
Don't know yet. :-)
>> * 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.
>
> Well, I don't know what this means, so I can't really comment.
Overview at http://docutils.sf.net/spec/pep-0258.html#transforms
> Sigh, another mailing list to join...
:-) Sign up for the docutils-develop@lists.sf.net mailing list at
http://lists.sourceforge.net/lists/listinfo/docutils-users .
>> * Encoding support.
>
> This is what codes.Stream{Reader,Writer} are for.
I've had enough trouble grokking Unicode encodings. The docs for the
codecs module are rather opaque and beyond my patience at the moment.
Do you know of a gentle introduction?
Having gone through the pain of figuring it all out, I'd rather
relieve the client code (and thus, Docutils developers) from the
responsibility of handling Unicode decoding & encoding (unless it/they
want to, of course!). So it's handled by the I/O classes. If it's
better to do the handling with codecs.StreamReader/.StreamWriter,
that's an implementation detail. I'm comfortable with the current
set-up; if you're not: patches welcome!
>> The I/O classes are really just implementation details. Perhaps they
>> wouldn't be objectionable if better convenience functions existed?
>
> Perhaps.
>
>> ``docutils.core.publish()`` provides a dirt-simple interface for
>> file-to-file command-line processing (including stdin-to-stdout).
>> Would a ``publish_string`` convenience funcion (providing
>> string-to-string programmatic processing) appease you? Given that,
>> you could do your own I/O.
>
> True.
I've added convenience functions to docutils.core, complete with
documentation: "publish_file()" for file-like object I/O (example in
tools/buildhtml.py) and "publish_string()" for string I/O (example in
tools/pep2html.py). Please take a look. I've also renamed the old
"publish()" function to "publish_cmdline()" to emphasize its
relationship to command-line front-end tools.
--
David Goodger <goodger@users.sourceforge.net> 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/