Re: [Xmlgraphics-fop Wiki] Update of "ApiRequirements" by JeremiasMaerki

[Glen Mazza <gm...@apache.org>]

+ == HR8 ==

>+ 
>+ (jeremias, 2005-06-26) At some point we should localize the clear-text feedback from the validation and layout process. If FOP is used in an end-user application, the errors and warning must be understandable to not-so-technical people.
>+ 
>  
>


Most validation messages are now centralized in FONode's message 
functions, so a Xalan-style i18n (language files, etc.) can be done much 
more easily right now.  Understanding DTD content model error messages 
(+, *, etc.) is much less mentally challenging than XSL FO stylesheet 
design, anyone who cannot handle the former will not be able to do that 
latter anyway.  I would not want to mask knowledge of this from the 
user--along with XSL, it's a Very Good Thing for them to learn, and any 
questions they may have on this on the FOP-USER list would happily be 
answered by other users with no effort from us.  (Although Andreas tends 
to answer such questions anyway, they are like candy to him. ;-)

We want our users to be very, very smart and confident at the 
office--much more Java and XML-knowledgable than others at the office 
who would recommend proprietary technologies for report generation.  
Getting rid of TraxInputHandler and XSLTInputHandler and having them 
learn standard JAXP instead was one way to accomplish this goal.  Having 
them learning DTD content-model syntax helps us in another.


>+ == wL1 ==
>+ 
>+ (jeremias, 2005-06-26) I want renderer selection by MIME type even though there's technically no MIME type for a print renderer.
>  
>


Hmmm, you have wanted this for a long time now.  MIME types are hard to 
remember--most users *don't* have them etched in memory like you do--and 
we don't get the auto-complete from IDE's that we can get from 
Fop.RENDER_XXX.   Nor have we had much demand for them, or complaints 
about the integer constants. 

At the same time though it would be better for the project for you to 
accomplish what you want here, so you can better and more productively 
focus on other things.  I would recommend first having MIME types *in 
addition to* integer constants--i.e., add an additional "convenience" 
constructor in apps.Fop that takes the String MIME type and converts it 
there to an integer for subsequent use by the system.  Step #2 would be 
to come up with a plan for the team to replace the constants with 
strings internally, and then proceed if they approve.  Steps #3, #4, 
etc. are whatever you're planning for this afterwards.  But I'm taking 
myself out of this discussion--if the team wants MIME types instead of 
integer constants, MIME types it will be.

My main concern though is that I would recommend against direct access 
of RendererFactory by embedded users--keep them referencing apps.Fop or 
FOUserAgent for their configurations (or Avalon configuration file, 
etc.) if possible.  Those two classes form the shield that allow present 
and future committers to do anything they want to FOP's internal code 
without concern for backwards compatibility.  Like FOTreeBuilder, 
RendererFactory is within our black box, and should be subject to 
renaming/modification/deletion at any time.

Glen