[Docutils-develop] split output (was Re: sandbox/tibs/pysource/notes thoughts.txt)

[David G. <go...@us...>]

[David]
>>>> I don't know how this will work yet.  Perhaps the Writer and/or I/O
>>>> object will handle forests (multiple trees).  Perhaps the doctree will
>>>> remain monolithic, and a transform will insert "split here" indicators.
>>>> It's all up in the air.

[Richard]
>>> The "split here" part worries me - that then implies the HTML Writer
>>> knows how to output multiple files, which I don't believe it should. It
>>> should be the job of the pysource "framework" (the bit that drives the
>>> parse -> transform -> writer mechanisms) to decide what files need to be
>>> written and how they should be written.

[David]
>> Problem is, PySource is a *Reader*, which doesn't know and shouldn't care
>> about final output.

[Richard]
> I don't think pysource is going to be able to get away with being *just* a
> Reader. The one-source-to-many issue kinda throws a huge spanner in the
> works.

The one-source-to-many issue is pervasive, not specific to PySource at all.
For example, I'd like to be able to split the "reStructuredText Markup
Specification" into multiple .html files, one per first-level section (and
perhaps even one per second-level section).  "The Docutils Document Tree: A
Guide to the Docutils DTD", whose HTML is now up to 208K, is becoming much
too big.  And it's far from finished!

I agree that the HTML Writer shouldn't have to know how to split & write
multiple files.  This may be a job for a specialized I/O object, like
"MultiFileOutput".  It will need some earlier support though, such as
reference adjustment (any given reference may need to point to
``href="file#id"`` instead of just ``href="#id"``).  Perhaps I/O objects
should become full-fledged components (i.e. subclasses of
``docutils.Component``, as are Readers, Parsers, and Writers now), and thus
have associated option/setting specs and transforms.

In any case, we should try to find an elegant, general solution to the
problem.  We may not get there with the first attempt, or even the second,
but that's OK.  One thing this project has taught me is to let go of code,
to be willing to sacrifice it when it has proven unfit.

-- 
David Goodger  <go...@us...>  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/