[Doc-SIG] simple use of docutils
Michael Hudson
mwh@python.net
17 Oct 2002 11:30:17 +0100
David Goodger <goodger@users.sourceforge.net> writes:
> Michael Hudson wrote:
> >>> WHY can't I just pass a filename or a file-like object in as
> >>> destination?
> >>
> >> I'm trying to provide a uniform interface, no matter the input
> >> source (string, single file, multiple files in directories, Python
> >> module, Python package) and output destination (string, single
> >> file, multiple files), not all of which are implemented yet. The
> >> I/O classes store attributes of their data stores, such as paths
> >> and encodings; the I/O classes handle the text decoding & encoding.
> >
> > I object (faintly :) to your invention of new classes for this. Why
> > not use what's already there, i.e. the file interface?
> >
> > If you want strings, use a StringIO. The codecs.Stream{Reader,Writer}
> > classes handle encodings. Etc.
> ...
> > It would be nice if you didn't *have* to learn a new set of classes
> > to use docutils. The mantra "easy things should be easy, difficult
> > things should be possible" is one I'm quite attached to.
>
> I can see your point, and I agree with what you say in the abstract.
> The I/O classes may be a case of adding functionality before it's
> required. However, I'm currently thinking about adding *more*
> functionality to these classes. When you combine all the features
> Docutils needs from its I/O, I'm not convinced that doing it piecemeal
> is better:
>
> * 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.
> * 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?
> * 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.
Sigh, another mailing list to join...
> * Encoding support.
This is what codes.Stream{Reader,Writer} are for.
> 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.
> Of course, I'm open to convincing arguments. Or better yet,
> convincing code. :-)
Still no progress on this front, I'm afraid.
Cheers,
M.
--
US elections
For those of you fearing that the rest of the world might be
making fun of the US because of this: Rest assured, we are.
-- http://www.advogato.org/person/jameson/diary.html?start=12