You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Vincent Hennebert <vh...@gmail.com> on 2009/02/10 13:22:01 UTC
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.
<snip/>
> <section id="introduction">
> <title>Introduction</title>
> <p>
> - 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
> <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
> - 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.
<snip/>
Vincent
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation:
content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Posted by Vincent Hennebert <vh...@gmail.com>.
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:
>>>>
>> <snip/>
>>>>> <section id="introduction">
>>>>> <title>Introduction</title>
>>>>> <p>
>>>>> - 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
>>>>> <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
>>>>> - 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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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:
> >>
> <snip/>
> >>> <section id="introduction">
> >>> <title>Introduction</title>
> >>> <p>
> >>> - 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
> >>> <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
> >>> - 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
Posted by Chris Bowditch <bo...@hotmail.com>.
Vincent Hennebert wrote:
Hi Vincent,
> Jeremias Maerki wrote:
>
>>On 10.02.2009 13:22:01 Vincent Hennebert wrote:
>>
>>>Hi Jeremias,
>>>
>>>A few suggestions:
>>>
>
> <snip/>
>
>>>> <section id="introduction">
>>>> <title>Introduction</title>
>>>> <p>
>>>>- 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
>>>> <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
>>>>- 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.
<snip/>
Chris
Re: svn commit: r741616 - in /xmlgraphics/fop/branches/Temp_AreaTreeNewDesign/src/documentation:
content/xdocs/trunk/intermediate.xml resources/images/if-architecture-overview.png
Posted by Vincent Hennebert <vh...@gmail.com>.
Jeremias Maerki wrote:
> On 10.02.2009 13:22:01 Vincent Hennebert wrote:
>> Hi Jeremias,
>>
>> A few suggestions:
>>
<snip/>
>>> <section id="introduction">
>>> <title>Introduction</title>
>>> <p>
>>> - 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
>>> <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
>>> - 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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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.
>
> <snip/>
> > <section id="introduction">
> > <title>Introduction</title>
> > <p>
> > - 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
> > <a href="http://www.w3.org/TR/2001/REC-xsl-20011015/slice1.html#section-N742-Formatting">XSL-FO specification in chapter 1.1.2</a>.
> > - 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).
> <snip/>
>
> Vincent
Jeremias Maerki