Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Jeremias Maerki wrote: > On 11.02.2009 13:07:12 Vincent Hennebert wrote: >> Jeremias Maerki wrote: >>> On 10.02.2009 13:22:01 Vincent Hennebert wrote: Hi Jeremias, A few suggestions: >> > >Introduction > > -The intermediate format (IF) is a proprietary XML format that > represents the area tree > -generated by the layout engine. The area tree is conceptually > defined in the > +Apache FOP now provides two different so-called intermediate > formats. The first one > +(let's call it the area tree XML format) is basically a 1:1 XML > representation of the FOP's > +area tree generated by the layout engine. The area tree is > conceptually defined in the > href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO > specification in chapter 1.1.2. > -The IF can be generated through the area tree XML Renderer (the > XMLRenderer). Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will probably allow to avoid confusion in the future. >>> -1 to that. Will break backwards-compatibility for those who are using >>> this renderer directly. It would break at least two pieces of software I >>> have. >> Breaking backwards-compatibility because of an important change in an >> API is a thing, simply have a class renamed is a non-issue if you ask >> me. It’s just a small search/replace and recompilation. > > Ok, then "simply" rename FopFactory to FormattingObjectsProcessorFactory > and see what the FOP users will tell you. That has of course nothing to do. We are talking about a change that would bring some clarification. Admittedly small, but every little helps. >> To make things a little bit smoother though, XMLRenderer could be made >> deprecated with a suggestion to switch to AreaTree[XML]Renderer. > > And how would that make the situation any better? That would give users the time to plan the adaptation of their code. >>> If you you generate SAX events >>> (AbstractXMLRenderer.setContentHandler()), working with MIME types isn't >>> enough. >> I’m missing the point here? > > If you're selecting the XMLRenderer via its MIME type, renaming > XMLRenderer to anything else is a non-issue because it would be handled > inside FOP. But if you need to send the AT XML as SAX events somewhere > you have to instantiate XMLRenderer yourself. Hmmm. But can’t that be done through the renderer options? >>> Besides, I don't think that would really improve the whole thing >>> much. After all, with the new IF, we're not primarily talking about >>> renderers but something else (IFDocumentHandler/IFPainter). >> It’s never too obvious. After all, the two sections in the documentation >> are very similar. > > Yes, and there is just no way to make them any more dissimilar. Both are > XML-based intermediate formats. Both have their use cases. Better to > keep them close together so people know that there are two and how to > deal with them. Which is an additional reason why XMLRenderer could do with a name change IMO. However, I’ve just seen Chris’ answer, and the majority decides. Vincent
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Vincent Hennebert wrote: Hi Vincent, Jeremias Maerki wrote: On 10.02.2009 13:22:01 Vincent Hennebert wrote: Hi Jeremias, A few suggestions: Introduction -The intermediate format (IF) is a proprietary XML format that represents the area tree -generated by the layout engine. The area tree is conceptually defined in the +Apache FOP now provides two different so-called intermediate formats. The first one +(let's call it the area tree XML format) is basically a 1:1 XML representation of the FOP's +area tree generated by the layout engine. The area tree is conceptually defined in the http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO specification in chapter 1.1.2. -The IF can be generated through the area tree XML Renderer (the XMLRenderer). Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will probably allow to avoid confusion in the future. -1 to that. Will break backwards-compatibility for those who are using this renderer directly. It would break at least two pieces of software I have. Breaking backwards-compatibility because of an important change in an API is a thing, simply have a class renamed is a non-issue if you ask me. It’s just a small search/replace and recompilation. To make things a little bit smoother though, XMLRenderer could be made deprecated with a suggestion to switch to AreaTree[XML]Renderer. I'm sorry I agree with Jeremias here. The AreaTreeRenderer is part of the user facing API if you work with the Intermediate Format as many folks do. The reasons you state (about the meaning of the class not being clear enough) aren't good enough IMO to warrant breaking backwards compatibility. -1 to this change. Chris
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
On 11.02.2009 13:07:12 Vincent Hennebert wrote: > Jeremias Maerki wrote: > > On 10.02.2009 13:22:01 Vincent Hennebert wrote: > >> Hi Jeremias, > >> > >> A few suggestions: > >> > > >>> > >>>Introduction > >>> > >>> -The intermediate format (IF) is a proprietary XML format that > >>> represents the area tree > >>> -generated by the layout engine. The area tree is conceptually > >>> defined in the > >>> +Apache FOP now provides two different so-called intermediate > >>> formats. The first one > >>> +(let's call it the area tree XML format) is basically a 1:1 XML > >>> representation of the FOP's > >>> +area tree generated by the layout engine. The area tree is > >>> conceptually defined in the > >>> >>> href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO > >>> specification in chapter 1.1.2. > >>> -The IF can be generated through the area tree XML Renderer (the > >>> XMLRenderer). > >> Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will > >> probably allow to avoid confusion in the future. > > > > -1 to that. Will break backwards-compatibility for those who are using > > this renderer directly. It would break at least two pieces of software I > > have. > > Breaking backwards-compatibility because of an important change in an > API is a thing, simply have a class renamed is a non-issue if you ask > me. It’s just a small search/replace and recompilation. Ok, then "simply" rename FopFactory to FormattingObjectsProcessorFactory and see what the FOP users will tell you. > To make things a little bit smoother though, XMLRenderer could be made > deprecated with a suggestion to switch to AreaTree[XML]Renderer. And how would that make the situation any better? > > > If you you generate SAX events > > (AbstractXMLRenderer.setContentHandler()), working with MIME types isn't > > enough. > > I’m missing the point here? If you're selecting the XMLRenderer via its MIME type, renaming XMLRenderer to anything else is a non-issue because it would be handled inside FOP. But if you need to send the AT XML as SAX events somewhere you have to instantiate XMLRenderer yourself. > > > Besides, I don't think that would really improve the whole thing > > much. After all, with the new IF, we're not primarily talking about > > renderers but something else (IFDocumentHandler/IFPainter). > > It’s never too obvious. After all, the two sections in the documentation > are very similar. Yes, and there is just no way to make them any more dissimilar. Both are XML-based intermediate formats. Both have their use cases. Better to keep them close together so people know that there are two and how to deal with them. Jeremias Maerki
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Jeremias Maerki wrote: > On 10.02.2009 13:22:01 Vincent Hennebert wrote: >> Hi Jeremias, >> >> A few suggestions: >> >>> >>>Introduction >>> >>> -The intermediate format (IF) is a proprietary XML format that >>> represents the area tree >>> -generated by the layout engine. The area tree is conceptually >>> defined in the >>> +Apache FOP now provides two different so-called intermediate >>> formats. The first one >>> +(let's call it the area tree XML format) is basically a 1:1 XML >>> representation of the FOP's >>> +area tree generated by the layout engine. The area tree is >>> conceptually defined in the >>> >> href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO >>> specification in chapter 1.1.2. >>> -The IF can be generated through the area tree XML Renderer (the >>> XMLRenderer). >> Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will >> probably allow to avoid confusion in the future. > > -1 to that. Will break backwards-compatibility for those who are using > this renderer directly. It would break at least two pieces of software I > have. Breaking backwards-compatibility because of an important change in an API is a thing, simply have a class renamed is a non-issue if you ask me. It’s just a small search/replace and recompilation. To make things a little bit smoother though, XMLRenderer could be made deprecated with a suggestion to switch to AreaTree[XML]Renderer. > If you you generate SAX events > (AbstractXMLRenderer.setContentHandler()), working with MIME types isn't > enough. I’m missing the point here? > Besides, I don't think that would really improve the whole thing > much. After all, with the new IF, we're not primarily talking about > renderers but something else (IFDocumentHandler/IFPainter). It’s never too obvious. After all, the two sections in the documentation are very similar. Vincent
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
On 10.02.2009 13:22:01 Vincent Hennebert wrote: > Hi Jeremias, > > A few suggestions: > > > Author: jeremias > > Date: Fri Feb 6 16:27:13 2009 > > New Revision: 741616 > > > > URL: http://svn.apache.org/viewvc?rev=741616&view=rev > > Log: > > Updated intermediate format documentation. > > > > Added: > > > > xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation/resources/images/if-architecture-overview.png > >(with props) > > What software did you use to produce this image? You may want to also > commit the source file, so that others can edit it if necessary. Inkscape. I'll add the original file shortly. > > > > > >Introduction > > > > -The intermediate format (IF) is a proprietary XML format that > > represents the area tree > > -generated by the layout engine. The area tree is conceptually > > defined in the > > +Apache FOP now provides two different so-called intermediate > > formats. The first one > > +(let's call it the area tree XML format) is basically a 1:1 XML > > representation of the FOP's > > +area tree generated by the layout engine. The area tree is > > conceptually defined in the > > > href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO > > specification in chapter 1.1.2. > > -The IF can be generated through the area tree XML Renderer (the > > XMLRenderer). > > Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will > probably allow to avoid confusion in the future. -1 to that. Will break backwards-compatibility for those who are using this renderer directly. It would break at least two pieces of software I have. If you you generate SAX events (AbstractXMLRenderer.setContentHandler()), working with MIME types isn't enough. Besides, I don't think that would really improve the whole thing much. After all, with the new IF, we're not primarily talking about renderers but something else (IFDocumentHandler/IFPainter). > > > Vincent Jeremias Maerki
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation: content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Hi Jeremias, A few suggestions: > Author: jeremias > Date: Fri Feb 6 16:27:13 2009 > New Revision: 741616 > > URL: http://svn.apache.org/viewvc?rev=741616&view=rev > Log: > Updated intermediate format documentation. > > Added: > > xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation/resources/images/if-architecture-overview.png >(with props) What software did you use to produce this image? You may want to also commit the source file, so that others can edit it if necessary. > >Introduction > > -The intermediate format (IF) is a proprietary XML format that > represents the area tree > -generated by the layout engine. The area tree is conceptually > defined in the > +Apache FOP now provides two different so-called intermediate > formats. The first one > +(let's call it the area tree XML format) is basically a 1:1 XML > representation of the FOP's > +area tree generated by the layout engine. The area tree is > conceptually defined in the > href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting";>XSL-FO > specification in chapter 1.1.2. > -The IF can be generated through the area tree XML Renderer (the > XMLRenderer). Renaming this class into AreaTreeRenderer or AreaTreeXMLRenderer will probably allow to avoid confusion in the future. Vincent