The need for multiple passes over a document

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.

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
----------------------------------------------------------

A language that doesn’t affect the way you think about programming is  
not worth knowing.

-— Alan Perlis