[Doc-SIG] simple use of docutils

[Michael Hudson]

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