maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lukas Theussl <>
Subject Re: svn commit: r558696 - in /maven/doxia/site: ./ src/site/ src/site/apt/ src/site/apt/developers/ src/site/apt/macros/ src/site/apt/modules/ src/site/apt/references/ src/site/fml/ src/site/resources/images/
Date Tue, 24 Jul 2007 08:49:54 GMT
[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.


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:
> For additional commands, e-mail:

View raw message