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
