From 65e7ec5d8c6a6ce76b90d830776662d6d2638e72 Mon Sep 17 00:00:00 2001 From: Keiron Liddle Date: Wed, 6 Jun 2001 12:34:09 +0000 Subject: [PATCH] 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 --- docs/xml-docs/fop.xml | 2 + docs/xml-docs/fop/architecture.xml | 25 +++++---- docs/xml-docs/fop/examples.xml | 2 +- docs/xml-docs/fop/implemented.xml | 80 ++++----------------------- docs/xml-docs/fop/involved.xml | 7 +-- docs/xml-docs/fop/readme.xml | 7 +-- docs/xml-docs/fop/running.xml | 2 +- docs/xml-docs/fop/svg.xml | 45 ++++++++++++++++ docs/xml-docs/fop/testing.xml | 87 ++++++++++++++++++++++++++++++ 9 files changed, 170 insertions(+), 87 deletions(-) create mode 100644 docs/xml-docs/fop/svg.xml create mode 100644 docs/xml-docs/fop/testing.xml 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 @@ + + 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)

-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.

-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 createGraphic() 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.

-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. +

+ +

+The AWTRenderer and the PrintRenderer use Batik directly to draw the SVG image +into the current java Graphics2D context.

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 @@

Developers will find the first steps to a test suite for all implemented formatting objects and - properties in xml-fop/docs/bugtests.

+ properties in xml-fop/test/xml/.

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

All other properties are not implemented.

 - -
    -
  • rect
    • -
  • circle
    • -
  • line
    • -
  • text - tref, tspan
    • -
  • path
    • -
  • polygon
    • -
  • ellipse
    • -
  • g
    • -
  • svg (inside)
    • -
  • image
    • -
  • use
    • -
  • defs (including referenced items not in defs element)
    • -
  • linearGradient
    • -
  • radialGradient
    • -
  • stop
    • -
- - -
    -
  • style
    • -
  • fill (style)
    • -
  • stroke (style)
    • -
  • stroke-width (style)
    • -
  • stroke-dasharray (style)
    • -
  • stroke-offset (style)
    • -
  • stroke-linecap (style)
    • -
  • stroke-linejoin (style)
    • -
  • stroke-miterlimit (style)
    • -
  • stop-color (style)
    • -
  • color (style)
    • -
  • font (style)
    • -
  • font-size (style)
    • -
  • font-family (style)
    • -
  • font-weight (style)
    • -
  • font-style (style)
    • -
  • x
    • -
  • y
    • -
  • x1
    • -
  • y1
    • -
  • x2
    • -
  • y2
    • -
  • r
    • -
  • cx
    • -
  • cy
    • -
  • x (list)
    • -
  • y (list)
    • -
  • dx
    • -
  • dy
    • -
  • transform
    • -
  • rotate (transform)
    • -
  • translate (transform)
    • -
  • scale (transform)
    • -
  • matrix (transform)
    • -
  • skewX (transform)
    • -
  • skewY (transform)
    • -
  • d
    • -
  • id
    • -
  • width
    • -
  • height
    • -
  • xlink:href
    • -
  • refX
    • -
  • refY
    • -
  • offset
    • -
  • points
    • -
  • fx
    • -
  • fy
    • -
+ +

+FOP uses Batik 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. +

+

+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. +

 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. If you want to contribute to the development of Fop you should subscribe, because it is important that you follow changes being made.

- -

If you want to contribute code (p.e. a bugfix) or documentation (p.e. an additional example), please do the following:

+ +

If you want to contribute code (p.e. a bugfix), a test or documentation (p.e. an additional example), please do the following:

1) Make sure your code doesn't break the existing one and that Fop still compiles.

2) Create a file which shows the differences to the existing code.

-

3) Send this file to fop-dev@xml.apache.org.

+

3) Send this file to fop-dev@xml.apache.org.

One of the committers will test your code and commit it to the code repository.

+

If you have a test or useful bug test you should read this page.

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 here).

 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.

-

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. +

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.

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 @@

  • An XSLT processor
    • -
  • The SVG library batik.jar is the library from the batik project at xml.apache.org. +
  • The SVG library batik.jar is the library from the batik project at xml.apache.org.
  • The imaging library Jimi from Sun
    • 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 @@ + + + + + + +

    +FOP uses the SVG library from Batik to handle SVG. +This format can be handled as an fo:instream-foreign-object or in a separate +file referenced with fo:external-graphic. 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. +

    +

    +The AWT and Print renderers simply use batik to draw the SVG into a graphic. +

    +

    +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. +

    +     + + +

    +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.
    +java org.apache.batik.apps.rasterizer.Main -m application/pdf document.svg +
    +This will output the svg document as "document.pdf" containing a PDF rendering of +the SVG file. +

    +

    +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. +

    +

    +For more information see Batik for +how transocders work. +

    +     + + +     + 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 @@ + + + + + + +

    +Testing is an important part of getting FOP to operate correctly and conform to the +necessary standards. +

    +

    +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. +

    +

    +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. +

    +     + + +

    +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. +

    +

    +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. +

    +

    +A system test is one that tests the abitlity of FOP to handle a number of different +elements together. +

    +

    +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. +

    + +     + +

    +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. +

    +     + + +

    +The tests are stored in the "<cvs_repository>/test" directory. +

    +

    +You can run the tests by specifying the build target "test" ie:
    +build.sh test +

    +

    +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. +

    +

    +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. +

    +

    +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. +

    +     + + +

    +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. +

    +     +     + -- 2.39.5