diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/xml-docs/fop.xml | 2 | ||||
| -rw-r--r-- | docs/xml-docs/fop/architecture.xml | 25 | ||||
| -rw-r--r-- | docs/xml-docs/fop/examples.xml | 2 | ||||
| -rw-r--r-- | docs/xml-docs/fop/implemented.xml | 80 | ||||
| -rw-r--r-- | docs/xml-docs/fop/involved.xml | 7 | ||||
| -rw-r--r-- | docs/xml-docs/fop/readme.xml | 7 | ||||
| -rw-r--r-- | docs/xml-docs/fop/running.xml | 2 | ||||
| -rw-r--r-- | docs/xml-docs/fop/svg.xml | 45 | ||||
| -rw-r--r-- | docs/xml-docs/fop/testing.xml | 87 |
9 files changed, 170 insertions, 87 deletions
diff --git a/docs/xml-docs/fop.xml b/docs/xml-docs/fop.xml index 308f7b0a6..fd6710fae 100644 --- a/docs/xml-docs/fop.xml +++ b/docs/xml-docs/fop.xml @@ -13,9 +13,11 @@ <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/> diff --git a/docs/xml-docs/fop/architecture.xml b/docs/xml-docs/fop/architecture.xml index 30165e3e0..3312e842a 100644 --- a/docs/xml-docs/fop/architecture.xml +++ b/docs/xml-docs/fop/architecture.xml @@ -321,22 +321,27 @@ You can find UML diagramms for all Fop packages (latest release version) <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> diff --git a/docs/xml-docs/fop/examples.xml b/docs/xml-docs/fop/examples.xml index c2019a6d7..c3a148731 100644 --- a/docs/xml-docs/fop/examples.xml +++ b/docs/xml-docs/fop/examples.xml @@ -51,7 +51,7 @@ </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> diff --git a/docs/xml-docs/fop/implemented.xml b/docs/xml-docs/fop/implemented.xml index 74cd3fb20..3de5b5233 100644 --- a/docs/xml-docs/fop/implemented.xml +++ b/docs/xml-docs/fop/implemented.xml @@ -221,75 +221,17 @@ border and padding shorthand properties <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> diff --git a/docs/xml-docs/fop/involved.xml b/docs/xml-docs/fop/involved.xml index 2f61c6b4d..1d645268d 100644 --- a/docs/xml-docs/fop/involved.xml +++ b/docs/xml-docs/fop/involved.xml @@ -31,12 +31,13 @@ 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> diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml index 1aa59258a..5604e3793 100644 --- a/docs/xml-docs/fop/readme.xml +++ b/docs/xml-docs/fop/readme.xml @@ -49,9 +49,10 @@ 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 diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml index d0f5890a8..3c2a7ed44 100644 --- a/docs/xml-docs/fop/running.xml +++ b/docs/xml-docs/fop/running.xml @@ -17,7 +17,7 @@ </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> diff --git a/docs/xml-docs/fop/svg.xml b/docs/xml-docs/fop/svg.xml new file mode 100644 index 000000000..14506b796 --- /dev/null +++ b/docs/xml-docs/fop/svg.xml @@ -0,0 +1,45 @@ +<?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> + diff --git a/docs/xml-docs/fop/testing.xml b/docs/xml-docs/fop/testing.xml new file mode 100644 index 000000000..34e27f581 --- /dev/null +++ b/docs/xml-docs/fop/testing.xml @@ -0,0 +1,87 @@ +<?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> + |