maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jason van Zyl <>
Subject Re: The need for multiple passes over a document
Date Mon, 28 Apr 2008 21:37:22 GMT

On 28-Apr-08, at 12:18 PM, Vincent Massol wrote:
> On Apr 28, 2008, at 3:49 PM, Jason van Zyl wrote:
>> I was looking at the TOC macro and I feel what it's doing is wrong  
>> insofar as requiring a second pass to get the structure of the  
>> document.
>> There are definitely cases where you need to make multiple passes  
>> and the TOC macro is clearly one of them. Having to pass in the the  
>> whole source document and the parser to make the TOC macro work  
>> seem extreme to me.
>> I think that we should declaratively say, or determine, that the  
>> structure of the document is required by something in the page.  
>> Preprocess the page in a general way and not require passing in the  
>> whole document and parser again as that's pretty cumbersome for the  
>> implementor of a parser.
> In XWiki land, I parse the document once, which generates an AST of  
> Blocks. Then this AST is passed to macros.

Right, this would be the same as parsing the document into a  
StructureSink, but this is still not necessary most of the time. A  
macro could say it required the StructureSink to operate on, or we  
just always parse into the StructureSink and modify this and then  
render it.

> Note that one reason we build an in memory AST is to cache it in  
> order to serve pages faster (no need to reparse static elements -  
> only macros are reparsed).

Sure, but I think caching is orthogonal to this.

But passing in the parser and the document again to a macro is not good.

> -Vincent
>> I also noticed that the parsers are not threadsafe, I don't believe  
>> this was always the case and we should make them threadsafe again  
>> if it's true they aren't. I just looked at the APT parser and it  
>> doesn't look threadsafe to me but wouldn't take much to make it  
>> threadsafe.
>> I would like to take a pass at making the document structure  
>> requirement more general to avoid things like we're doing in the  
>> TOC macro. I would also like to take a pass at making the parsers  
>> threadsafe.
>> I think we should also just release 1.0 for the sake of the site  
>> plugin and then move on with the next version of Doxia. We need to  
>> remove the coupling of doxia to the site  plugin and move the core  
>> back to a simple set of parsers and sinks.
>> Thanks,
>> Jason



Jason van Zyl
Founder,  Apache Maven
jason at sonatype dot com

Three people can keep a secret provided two of them are dead.

-- Unknown 

View raw message