<document id="config" label="Configuration" source="fop/configuration.xml" />
<document id="fonts" label="Fonts" source="fop/fonts.xml" />
<document id="extensions" label="Extensions" source="fop/extensions.xml" />
+ <document id="svg" label="SVG" source="fop/svg.xml" />
<separator/>
<document id="compiling" label="Compiling" source="fop/compiling.xml" />
<document id="embedding" label="Embedding" source="fop/embedding.xml" />
+ <document id="testing" label="Testing" source="fop/testing.xml" />
<document id="involved" label="Getting involved" source="fop/involved.xml" />
<document id="architecture" label="Architecture" source="fop/architecture.xml"/>
<separator/>
<s2 title="SVG">
<p>
-FOP supports some svg rendering. SVG is supported as an instream-foreign-object
-embedded in an FO document. FOP also supports rendering of an external SVG image.
+FOP supports svg rendering. SVG is supported as an instream-foreign-object
+embedded in an FO document or as an external SVG image.
</p>
<p>
-Since the intream object that contains the SVG returns a single fo area then
-the construction of the SVG document is handled differently. The SVG is created
-by calling the <code>createGraphic()</code> on each SVG element. The element is then
-responsible for loading the necessary information and child elements and creating
-the corresponding SVG DOM element. When the FO tree is being layed out the
-SVG tree is turned into the SVG DOM document which is stored for later rendering.
+If the svg is embedded in an instream-foreign-object then all the elements and
+attributes are read directly and converted into an SVG DOM representation
+using the Batik library. This is then stored as a DOM until required for rendering.
+The rendering process depends on the what type of renderer is being used.
</p>
<p>
-The SVG document is then held as a DOM tree which is then rendered by going through
-the elements of the tree and rendering then in turn.
+The SVG DOM is rendered in the PDF renderer by using the abitlity of Batik to render
+DOM to a Graphics2D. First the DOM is converted into an intermediate representation
+then this is rendered to a PDFGraphics2D graphic object which writes the drawing
+instructions directly as PDF markup.
+</p>
+
+<p>
+The AWTRenderer and the PrintRenderer use Batik directly to draw the SVG image
+into the current java Graphics2D context.
</p>
<p>
</li>
</ul>
<p>Developers will find the first steps to a test suite for all implemented formatting objects and
- properties in xml-fop/docs/bugtests.</p>
+ properties in xml-fop/test/xml/.</p>
</s1>
<p>All other properties are not implemented.</p>
</s2>
- <s2 title="3) SVG elements supported">
- <ul>
- <li>rect</li>
- <li>circle</li>
- <li>line</li>
- <li>text - tref, tspan</li>
- <li>path</li>
- <li>polygon</li>
- <li>ellipse</li>
- <li>g</li>
- <li>svg (inside)</li>
- <li>image</li>
- <li>use</li>
- <li>defs (including referenced items not in defs element)</li>
- <li>linearGradient</li>
- <li>radialGradient</li>
- <li>stop</li>
- </ul>
- </s2>
- <s2 title="4) SVG properties supported">
- <ul>
- <li>style</li>
- <li>fill (style)</li>
- <li>stroke (style)</li>
- <li>stroke-width (style)</li>
- <li>stroke-dasharray (style)</li>
- <li>stroke-offset (style)</li>
- <li>stroke-linecap (style)</li>
- <li>stroke-linejoin (style)</li>
- <li>stroke-miterlimit (style)</li>
- <li>stop-color (style)</li>
- <li>color (style)</li>
- <li>font (style)</li>
- <li>font-size (style)</li>
- <li>font-family (style)</li>
- <li>font-weight (style)</li>
- <li>font-style (style)</li>
- <li>x</li>
- <li>y</li>
- <li>x1</li>
- <li>y1</li>
- <li>x2</li>
- <li>y2</li>
- <li>r</li>
- <li>cx</li>
- <li>cy</li>
- <li>x (list)</li>
- <li>y (list)</li>
- <li>dx</li>
- <li>dy</li>
- <li>transform</li>
- <li>rotate (transform)</li>
- <li>translate (transform)</li>
- <li>scale (transform)</li>
- <li>matrix (transform)</li>
- <li>skewX (transform)</li>
- <li>skewY (transform)</li>
- <li>d</li>
- <li>id</li>
- <li>width</li>
- <li>height</li>
- <li>xlink:href</li>
- <li>refX</li>
- <li>refY</li>
- <li>offset</li>
- <li>points</li>
- <li>fx</li>
- <li>fy</li>
- </ul>
+ <s2 title="3)SVG Support">
+<p>
+FOP uses <jump href="http://xml.apache.org/batik/">Batik</jump> directly for its SVG support. Therefore FOP supports the same
+elements and properties as are supported by Batik. As FOP is designed for
+rendering to a static medium then only static SVG is rendered.
+</p>
+<p>
+Due to some limitations in PDF some SVG images, particularly ones with effects
+or transparency, may not come out correctly. The images should still be rendered
+correctly for the AWT and Print renderers.
+</p>
</s2>
</s1>
fop-cvs-subscribe@xml.apache.org</jump>. If you want to contribute to the development of Fop you should subscribe,
because it is important that you follow changes being made. </p>
</s2>
- <s2 title="Contributing code and documentation">
- <p>If you want to contribute code (p.e. a bugfix) or documentation (p.e. an additional example), please do the following: </p>
+ <s2 title="Contributing code, tests and documentation">
+ <p>If you want to contribute code (p.e. a bugfix), a test or documentation (p.e. an additional example), please do the following: </p>
<p>1) Make sure your code doesn't break the existing one and that Fop still compiles.</p>
<p>2) Create a file which shows the differences to the existing code.</p>
- <p>3) Send this file to fop-dev@xml.apache.org.</p>
+ <p>3) Send this file to <jump href="mailto:fop-dev@xml.apache.org">fop-dev@xml.apache.org.</jump></p>
<p>One of the committers will test your code and commit it to the code repository.</p>
+ <p>If you have a test or useful bug test you should <jump href="testing.html">read this page</jump>.</p>
<p>BTW: The Apache project knows different roles for contributors, namely 'users', 'developers', 'committers' and the 'Project
Management Committee' (An explanation of these roles can be found <jump href="http://xml.apache.org/roles.html">here</jump>).</p>
</s2>
identified as such.
</p>
- <p>Another secondary goal is to promote the conversion of SVG into PDF. The most natural mechanism for doing so is within
- fo:instream-foreign-object FO's. The powerful graphics offered by both SVG and PDF are a natural fit, and it is
- desirable that FOP natively supports an SVG content processor for the fo:instream-foreign-object.
+ <p>Another secondary goal is to improve the conversion of SVG into PDF.
+ This includes the use of FOP to work as a transcoder for Batik to convert
+ an SVG document into a PDF document and the fully support embedding SVG inside
+ fo documents in an fo:instream-foreign-object.
</p>
<p>A final secondary goal is the continued refinement of the FOP design and implementation. In particular, maintaining the
</li>
<li>An XSLT processor
</li>
- <li>The SVG library batik.jar is the library from the batik project at xml.apache.org.
+ <li>The SVG library batik.jar is the library from the <jump href="http://xml.apache.org/batik/">batik project</jump> at xml.apache.org.
</li>
<li>The imaging library Jimi from Sun
</li>
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- SVG in FOP -->
+
+<s1 title="SVG in FOP">
+ <s2 title="Introduction">
+ <p>
+FOP uses the SVG library from <jump href="http://xml.apache.org/batik/">Batik</jump> to handle SVG.
+This format can be handled as an <code>fo:instream-foreign-object</code> or in a separate
+file referenced with <code>fo:external-graphic</code>. Either way the SVG document will be
+read in and converted into a DOM in Batik. This DOM will then be used by the renderer to
+create the graphical image.
+ </p>
+ <p>
+The AWT and Print renderers simply use batik to draw the SVG into a graphic.
+ </p>
+ <p>
+In the case of the PDF renderer there is a PDFGraphics2D class that Batik uses
+to render the image into. This class converts the drawing instructions into
+PDF markup which is placed into the current PDF document.
+ </p>
+ </s2>
+
+ <s2 title="Converting SVG to a PDF Document">
+ <p>
+It is possible to convert a standalone SVG document directly into a simple page PDF document.
+This is possible through the use of Batik's transcoder mechanism.<br/>
+<code>java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg</code>
+<br/>
+This will output the svg document as "document.pdf" containing a PDF rendering of
+the SVG file.
+ </p>
+ <p>
+It is also possible to specify the width and/or height of the PDF document.
+Currently the SVG image is simply scaled in PDF so the result my not be the best possible.
+ </p>
+ <p>
+For more information see <jump href="http://xml.apache.org/batik/">Batik</jump> for
+how transocders work.
+ </p>
+ </s2>
+
+
+</s1>
+
--- /dev/null
+<?xml version="1.0" standalone="no"?>
+
+<!-- Testing FOP -->
+
+<s1 title="Testing FOP">
+ <s2 title="">
+ <p>
+Testing is an important part of getting FOP to operate correctly and conform to the
+necessary standards.
+ </p>
+ <p>
+A testing system has been set up that works with as a build target when developing
+with FOP. A developer can run the tests after making changes to the code, the aim
+is to have the tests run to verfiy that nothing working has been broken.
+ </p>
+ <p>
+To setup the testing the developer must place a reference fop.jar in the
+"<cvs_repository>/test/reference/" directory. This jar will be dynamically
+loaded to create the reference output.
+ </p>
+ </s2>
+
+ <s2 title="Writing a Test">
+ <p>
+A test belongs to one of a few catagories. A basic test should excercise one
+element in a number of situations such as changing a property. This should have
+at least one normal value, one border value and one invalid value. If the property
+can be of different types then this should also be included.
+ </p>
+ <p>
+A bug test is a test that is specifically aimed at a problem with FOP. That is, the test
+is not excercising the specification but rather a problem with FOP in handling a particular
+situation that is not exposed with the other testing.
+ </p>
+ <p>
+A system test is one that tests the abitlity of FOP to handle a number of different
+elements together.
+ </p>
+ <p>
+A test can consist of a complete fo document or a part of the document such as
+some elements that will be placed into the flow of a standard document.
+ </p>
+
+ </s2>
+ <s2 title="Submitting a Test">
+ <p>
+If you have a test which you think would be useful you should supply the
+test and a diff to the appropriate test suite xml file. Make sure that the
+test works as would be expected against the current build.
+ </p>
+ </s2>
+
+ <s2 title="How Testing Works">
+ <p>
+The tests are stored in the "<cvs_repository>/test" directory.
+ </p>
+ <p>
+You can run the tests by specifying the build target "test" ie: <br/>
+<code>build.sh test</code>
+ </p>
+ <p>
+This will then compare the current code in the local src directory to a specified
+release of FOP. Any differences between the current code and the output from
+the reference version will be reported. If the test previously passed then the
+test run will have failed.
+ </p>
+ <p>
+The testing is done by reading a test suite xml file, which corresponds to the
+standard testsuite.dtd supplied from w3c. This xml file contains a test xml
+file and an xsl file (which may simply copy the file). It also contains information
+such as if the test has passed and any comments.
+ </p>
+ <p>
+For FOP the testing is done by rendering all the testing documents using the
+XML renderer. The XML files are then compared to see if there are any differences.
+ </p>
+ </s2>
+
+ <s2 title="SVG Testing">
+ <p>
+The testing of SVG is not part of this testing system. SVG is tested for its rendering
+accuracy by using the transcoding mechanism via Batik. So that the only part that needs
+testing is how the SVG image is embedded inside the flow of the fo document.
+ </p>
+ </s2>
+</s1>
+
projects / xmlgraphics-fop.git / commitdiff