updates to website xml docs for svg and testing

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194272 13f79535-47bb-0310-9956-ffa450edef68

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
+"&lt;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 "&lt;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>
+