[replying to doxia-dev@ as I think this was meant to go there]
I'd like to chime in here and try to clarify a design issue that I've
been thinking about recently.
The general doxia philosophy is clear from your description, what is not
specified IMO is the separation of responsibilities of a parser and a sink.
IMO all our core modules should try to achieve a 1-1 translation of the
core doxia events *only*. In particular, a parser shouldn't add anything
to a model that's not in the original. Good example is the commit I had
to revert recently (for backward compat reasons): the xdoc parser emits
an anchor for each section event. That's because it is needed in the
xhtml output, but it also means that the anchor will end up explicitly
in any sink document you might choose, even where it doesn't make any
sense. IMO it's only the low-end sink that should produce such
format-dependent elements.
As an extreme example you might imagine feeding the xhtml output back
into an xdoc sink; closing the circle you would end up adding anchors
indefinetly. One way to ensure this doesn't happen is the test I have
outlined at DOXIA-134: parsing an arbitrary model and feeding it back
into the corresponding sink, should give you back the original
unchanged. I don't know if it's possible in practice to achieve this for
all our modules, but it would certainly be a good quality control.
So, as you say, a sink is ultimately responsible for the final format
and structure, a parser should just stupidly forward the events it
receives. The core modules should just do 1-1 translations. Any special
output features should be handled by a low-end sink (eg
SiteRendererSink) for the particular format where this is desired.
Thoughts?
-Lukas
Jason van Zyl wrote:
On 23 Jul 07, at 5:50 AM 23 Jul 07, Dennis Lundberg wrote:
This is excellent stuff Vincent!
I'm only missing one thing, that have been puzzling me since I got
involved with Doxia:
What is a Sink?
Parser -> emission of Doxia events -> Sink
A Sink consumes Doxia events in a resultant output format like Docbook,
PDF, or XHTML.
The upshot is that you can parse any front-end format, the parser is
responsible for emitting the standard Doxia events which can then be
consumed by any Doxia Sink. This is what allow us to parse the front-
end format like APT, FML, and Xdoc for the Maven site plugin and have
them all contribute to the final XHTML version of a site. All documents
being parsed results in a stream of Doxia events (paragraph, bold,
italic, text) which are then fed in the XHTML sink which results in a
set of XHTML pages.
A sink if ultimately responsible for the final format and structure.
So, for example, you can take a series of APT documents and have that
be fed into a Sink which makes a single PDF, a book, a site, or a Word
document. The Sink is fully responsible for the final output. Once you
have Doxia events you can leverage any existing Sink. So if you wanted
to integrate your custom XML format, or custom Wiki format, you would
create a Doxia parser which could then be fed into any Sink to produce
your desired final output.
Thanks,
Jason
----------------------------------------------------------
Jason van Zyl
Founder and PMC Chair, Apache Maven
jason at sonatype dot com
----------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
