From 1a3636171f599e31d9964fbcf6e32cfc3e6fbbf3 Mon Sep 17 00:00:00 2001 From: fotis Date: Mon, 5 Feb 2001 23:59:53 +0000 Subject: updating docs for 0.17 release git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194024 13f79535-47bb-0310-9956-ffa450edef68 --- docs/xml-docs/fop/architecture.xml | 7 +++- docs/xml-docs/fop/bugs.xml | 15 +++----- docs/xml-docs/fop/compiling.xml | 4 +- docs/xml-docs/fop/embedding.xml | 17 +++++++-- docs/xml-docs/fop/faq.xml | 76 ++------------------------------------ docs/xml-docs/fop/fonts.xml | 63 +++++++++++++++++++++++++++++-- docs/xml-docs/fop/implemented.xml | 13 +++++-- docs/xml-docs/fop/involved.xml | 2 +- docs/xml-docs/fop/limitations.xml | 9 +---- docs/xml-docs/fop/readme.xml | 2 +- docs/xml-docs/fop/resources.xml | 39 +++++++++++++++++++ docs/xml-docs/fop/running.xml | 7 ++-- docs/xml-docs/fop/specs.xml | 30 --------------- 13 files changed, 145 insertions(+), 139 deletions(-) create mode 100644 docs/xml-docs/fop/resources.xml delete mode 100644 docs/xml-docs/fop/specs.xml (limited to 'docs/xml-docs/fop') diff --git a/docs/xml-docs/fop/architecture.xml b/docs/xml-docs/fop/architecture.xml index 0ac6ada55..5d385281b 100644 --- a/docs/xml-docs/fop/architecture.xml +++ b/docs/xml-docs/fop/architecture.xml @@ -16,7 +16,7 @@ this class, a typical sequence is:

driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");

driver.addPropertyList("org.apache.fop.fo.StandardPropertyListMapping");

driver.addPropertyList("org.apache.fop.svg.SVGPropertyListMapping");

-

driver.setWriter(new PrintWriter(new FileWriter(args[1])));

+

driver.setOutputStream(new FileOutputStream(args[1]));

driver.buildFOTree(parser, fileInputSource(args[0]));

@@ -262,6 +262,11 @@ Rendering will not be discussed further in this document, as most of our current effort must concentrate on layout. Section 4.12 in the XSL WD discusses some issues applicable to rendering.

+ +

+You can find UML diagramms for all Fop packages (latest release version) +here.

+ diff --git a/docs/xml-docs/fop/bugs.xml b/docs/xml-docs/fop/bugs.xml index 01de7ffa4..1e8e69336 100644 --- a/docs/xml-docs/fop/bugs.xml +++ b/docs/xml-docs/fop/bugs.xml @@ -1,23 +1,18 @@ - - -

Please report bugs to the discussion list fop-dev@xml.apache.org and put - the word [BUG] in the subject line.

+

Please report bugs to bugzilla, the Apache bug + database. A copy of your bug report is sent automatically to the discussion list fop-dev@xml.apache.org.

Please make sure, before you report a bug, that it is not mentioned in the FAQ or - in the list of open bugs in the file STATUS in the start directory of the Fop - distribution.

-

Please make your description as concise as possible and send an example fo + in the list of open bugs at bugzilla.

+

Please make your description as concise as possible and add an example fo file with your report, which just demonstrates the problem. Thanks for your help!

 -

A list of known bugs can be found at the end of the file - Status in the root - of the Fop distribution.

+

A list of known bugs can be found at bugzilla.

 diff --git a/docs/xml-docs/fop/compiling.xml b/docs/xml-docs/fop/compiling.xml index 0c7209f86..f0d0339fb 100644 --- a/docs/xml-docs/fop/compiling.xml +++ b/docs/xml-docs/fop/compiling.xml @@ -16,8 +16,8 @@

The build process relies on finding following libraries in your classpath (the version numbers indicate that building with them has been successfully tested, other, later versions may work too:

    -
  • Xerces-J version 1.2.1 (xml parser)
    • -
  • Xalan version 1.2 (xslt processor)
    • +
  • Xerces-J version 1.2.1 (xml parser). Xerces-J version 1.3.0 does not work, because of a bug in Xerces!
    • +
  • Xalan version 1.2 (xslt processor). Xalan 2.0 is also supported.
  • bsf.jar (comes with Xalan)
  • jimi.jar (image processing library) this file is optional
diff --git a/docs/xml-docs/fop/embedding.xml b/docs/xml-docs/fop/embedding.xml index 90c319f49..ee70f75c7 100644 --- a/docs/xml-docs/fop/embedding.xml +++ b/docs/xml-docs/fop/embedding.xml @@ -5,11 +5,11 @@ - +

Instantiate org.apache.fop.apps.Driver. Once this class is instantiated, methods are called to set the Renderer to use, the (possibly multiple) ElementMapping(s) to - use and the PrintWriter to use to output the results of the + use and the OutputStream to use to output the results of the rendering (where applicable). In the case of the Renderer and ElementMapping(s), the Driver may be supplied either with the object itself, or the name of the class, in which case Driver will @@ -27,17 +27,26 @@

Once the FO Tree is built, the format() and render() methods may be called in that order.

-

Here is an example use of Driver from CommandLine.java:

+

Here is an example use of Driver:

Driver driver = new Driver();

driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);

driver.addElementMapping("org.apache.fop.fo.StandardElementMapping");

driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");

driver.addPropertyList("org.apache.fop.fo.StandardPropertyListMapping");

driver.addPropertyList("org.apache.fop.svg.SVGPropertyListMapping");

-

driver.setWriter(new PrintWriter(new FileWriter(args[1])));

+

driver.setOutputStream(new FileOutputStream(args[1]));

driver.buildFOTree(parser, fileInputSource(args[0]));

driver.format();

driver.render();

+

Have a look at the classes CommandLine or XalanCommandLine for complete examples.

+ + +

In the directory xml-fop/docs/examples/embedding you can find a working example how to use + Fop in a servlet. You can drop the fop.war into the webapps directory of Tomcat, then + go to a URL like this: +

+

http://localhost:8080/fop/fop?fo=/home/path/to/fofile.fo

+

You can also find the source code there in the file FopServlet.java

 diff --git a/docs/xml-docs/fop/faq.xml b/docs/xml-docs/fop/faq.xml index 5449035a4..f0dfba96e 100644 --- a/docs/xml-docs/fop/faq.xml +++ b/docs/xml-docs/fop/faq.xml @@ -1,77 +1,9 @@ - - - - Q: I can't find the source files for the formatting properties. The directories - where they should be are empty. Where can I find them? -

A: They are generated during the build process. So you should use the build script coming - with Fop at least once to generate these files. -

- - - - - - Q: Feature xxx of the XSL Working Draft 27 March 2000 does not work as it should. Why? -

A: First: Only a small subset of formatting objects and properties is - implemented at the moment. Please have a look at the section "Features", - which lists the supported fo and properties. Second: At the moment only - Working Draft 21 Apr 1999 is supported. -

- - - - - Q: When will the latest version of the XSL working draft be supported? -

Basic conformance to the latest XSL working draft is scheduled for fall 2000. -

- - - - - Q: Running FOP I get the following messages or something similar: - "WARNING: Unknown formatting object http://www.w3.org/XSL/Format/1.0^root" - and then a FATAL Error "Root element must be root, not default FO". - -

A: Make sure that you have specified as the namespace for fo the - following string: "http://www.w3.org/1999/XSL/Format". It is analogous - to the xslt namespace "http://www.w3.org/1999/XSL/Transform" -

- - - - - Q: The char ">" is inserted into the page number display like this - "formatting FOs into areas [1] [2] [3>>>>]". Is this a bug? -

A: No, a feature. It simply means that on that page an area - overflowed (ie there was not enough room to fit the text in).

 - - - - Q: It looks like FOP must be honoring font properties when it shouldn't be? - Example: According to the dtd coming with the xsl-fo spec inline-sequence - shouldn't have any attributes, but FOP doesn't reject them. - - -

A: Font properties are inherited down to individual characters. You can - specify font properties on any formatting object you like and any textual content - will inherit those properties (unless overriden by a closer ancestor). + +

The Fop faq has an own site. Please look here: + http://www.OWAL.co.uk:8090/

-

The dtd coming with the xsl-fo spec isn't correct in this respect. -

- - - - - Q: I need some additional fonts in FOP. How I can set embedding fonts? - - -

A: At present, FOP does not support any fonts other than the built-in fonts - Times, Helvetica, Courier, Symbol and ZapfDingbats. -

- - + - diff --git a/docs/xml-docs/fop/fonts.xml b/docs/xml-docs/fop/fonts.xml index 81a94aec5..01869e8e1 100644 --- a/docs/xml-docs/fop/fonts.xml +++ b/docs/xml-docs/fop/fonts.xml @@ -1,19 +1,19 @@ - +

FOP (building PDF files) normally supports only the base 14 font package defined in the Adobe PDF specification. That includes the following fonts: Helvetica, Times, Courier, Symbol and ZapfDingbats.

Font support in FOP can be extended by the addition of font metric files (written in XML) created from Adobe - Type 1 fonts. No other font types (TrueType, Type 0, Type 3, etc.) are supported at this time. The current method - of adding fonts to FOP requires the package to be recompiled. + Type 1 fonts and Truetype fonts. No other font types (Type 0, Type 3, etc.) are supported at this time. The current method + of adding fonts to FOP requires the package to be recompiled. You can also embed fonts into pdf files; see below.

As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP - contains a tool that can generate such a font metrics file from a PFM file. + contains a tool that can generate such a font metrics file from a PFM file, which normally comes with the font file.

Run the class org.apache.fop.fonts.apps.PFMReader to generate the XML file. Important: The tool does two @@ -91,4 +91,59 @@

+ +

Adding Truetype fonts is almost identical to the process of adding type 1 fonts. The main difference is in the first step.

+ +

As mentioned above you need an XML file containing font metrics to be able to use an additional font. FOP + contains a tool that can generate such a font metrics file from your truetype font file +

+

Create metrics for the fontfile (we assume the file has the name cmr10.ttf und to be in c:\myfonts\):

+

java org.apache.fop.fonts.apps.TTFReader -fn TCM -cn TCM -ef C:\myfonts\cmr10.ttf C:\myfonts\cmr10.ttf ttfcm.xml

+

the -fn option sets the font name (in the example to TCM )

+

the -cn option set the classname (in the example to CM)

+

the -ef option will try to embed to font at the given path when fop is running (you can + change that in the generated xml file).

+ + +

Open the class org.apache.fop.render.pdf.FontSetup and add entries to the ones present according to + the following example: +

+

+ fontInfo.addMetrics("F14", new ZapfDingbats()); +

+

+ fontInfo.addMetrics("F19", new TCM()); //This is the new entry. +

+

+ ... +

+

+ fontInfo.addFontProperties("F14", "ZapfDingbats", "normal", "normal"); +

+

+ fontInfo.addFontProperties("F19", "TCM", "normal", "normal"); //This is the new entry. +

+

Note: The class name to use is visible in the <class-name> element of the font metrics file. +

+ + +

In the src/codegen directory you find the font metrics files for the base 14 fonts. The are being transformed + during build into Java classes and then compiled. The newly generated font metrics file must be included in this + process. To do that open build.xml and add entries according to the following example: +

+

Look for the section "Initialization target" and add the following line at the end of it

+

<property name="tcm.xml" value="${build.codegen}/tcm.xml">

+

then search for the section "Generate the source code". At the end of this section you can find + templates for type 1 and truetype fonts. use them with your font name:

+

<xslt infile="${tcm.xml}" xsltfile="${ttffontfile.xsl}" + outfile="${build.src}/${replacestring}/render/pdf/fonts/TCM.java" smart="yes"/>

+ + +

edit conf\userconfig.xml and add TCM to the list of embedded fonts

+

Don't forget: If you have embedded fonts, you must run Fop with the flag -cuserconfig.xml, + otherwise the settings in userconfig.xml will not be read.

+ +

Rebuild FOP!

+ + diff --git a/docs/xml-docs/fop/implemented.xml b/docs/xml-docs/fop/implemented.xml index 86b0dd8aa..c4393d155 100644 --- a/docs/xml-docs/fop/implemented.xml +++ b/docs/xml-docs/fop/implemented.xml @@ -85,11 +85,18 @@ -

Not implemented: float, footnote, footnote-body

+
    +
  • footnote
    • +
  • footnote-body
    • +
+

Not implemented: float

 -

Not implemented: wrapper, marker, retrieve-marker

+
    +
  • wrapper
    • +
+

Not implemented: marker, retrieve-marker

 @@ -200,7 +207,7 @@
  • table-omit-header-at-break
  • text-align
  • text-align-last
    • -
  • textdecoration (only value "underline")
    • +
  • text-decoration
  • text-indent
  • top
  • white-space-collapse
    • diff --git a/docs/xml-docs/fop/involved.xml b/docs/xml-docs/fop/involved.xml index 68742cce9..8ce3d70c9 100644 --- a/docs/xml-docs/fop/involved.xml +++ b/docs/xml-docs/fop/involved.xml @@ -41,7 +41,7 @@ Management Committee' (An explanation of these roles can be found here).

     -

    At the moment Fop is mainly a tools to render XSL:FO files to pdf. Therefore if you want to contribute to Fop you should become +

    At the moment Fop is mainly a tool to render XSL:FO files to pdf. Therefore if you want to contribute to Fop you should become familiar with these standards. You can find their internet addresses on our website.

     diff --git a/docs/xml-docs/fop/limitations.xml b/docs/xml-docs/fop/limitations.xml index e56c1a5e4..33fcbc4cc 100644 --- a/docs/xml-docs/fop/limitations.xml +++ b/docs/xml-docs/fop/limitations.xml @@ -10,10 +10,7 @@

    -

    Only the property leader-length.optimum is used, so for all purposes you can use - "leader-length" instead. leader-length.minimum/maximum should be honored - for line-justification, but this does not happen. -

    +

    leader-length.minimum is not used at all

     @@ -79,9 +76,5 @@

    </fo:table>

     - - diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml index c95748d0b..91cec49ea 100644 --- a/docs/xml-docs/fop/readme.xml +++ b/docs/xml-docs/fop/readme.xml @@ -20,7 +20,7 @@ like XT or Xalan) or can be passed in memory as a DOM Document or (in the case of XT) SAX events.

    -

    The latest version of Fop is 0.16 and it supports the xsl:fo candidate release. +

    The latest version of Fop is 0.17 and it supports the xsl:fo candidate release. You can download Fop including a precompiled version, the source code and many example files to get you started. Pointers to introductions into xsl:fo can be found in the diff --git a/docs/xml-docs/fop/resources.xml b/docs/xml-docs/fop/resources.xml new file mode 100644 index 000000000..3906739ac --- /dev/null +++ b/docs/xml-docs/fop/resources.xml @@ -0,0 +1,39 @@ + + + + + + + +

    +     + + + + + + + + + diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml index b78212e6d..d796fc6e7 100644 --- a/docs/xml-docs/fop/running.xml +++ b/docs/xml-docs/fop/running.xml @@ -16,11 +16,12 @@ be included in your classpath. The jar file w3c.jar contains the compiled classes for the java svg bindings with some other DOM classes that are used by the SVG DOM bindings. The source for the svg java binding classes can be found at - - SVG Java bindings, currently they correspond to the CR-SVG-20000802 specification document. + SVG Java bindings, currently they correspond to the SVG Candidate Recommendation (02 November 2000). The other required files can be found at W3C DOM Java binding.

    d) Optional: Fop supports the jimi library for image processing, if it is in your classpath - when you build Fop. You can find it at java.sun.com + when you build Fop (the precompiled version supports jimi). You can find it at + java.sun.com

    @@ -108,7 +109,7 @@

    If you have problems running FOP, please have a look at the - FOP FAQ. If you don't find a solution there, + FOP FAQ. If you don't find a solution there, you can ask for help on the list fop-dev@xml.apache.org. Maybe it is a bug and maybe somebody is already working on it.

    diff --git a/docs/xml-docs/fop/specs.xml b/docs/xml-docs/fop/specs.xml deleted file mode 100644 index 708e6935b..000000000 --- a/docs/xml-docs/fop/specs.xml +++ /dev/null @@ -1,30 +0,0 @@ - - - - - - - -
      -
    • XSL-FO Candidate Recommendation (21 November 2000)
      • -
    • A dtd for the XSL-FO WD from October provided by N. Grigoriev from RenderX
      • -
    • Latest SVG Working draft
      • -
    • Supported SVG Candidate Recommendation
      • -
    • XML Recommendation
      • -
    • XSLT Recommendation
      • -
    • Portable Document Format (PDF) 1.3 Reference Manual
      • -
    • Simple API for XML (SAX)
      • -
    • Document Object Model (DOM)
      • -
    • Namespaces in XML Recommendation
      • -
    • Java JDK 1.1 Documentation
      • -
    -     - -
      -
    • Elliotte Rusty Harold: Chapter 15 on xsl:fo from his excellent xml book
      • -
    • Paul Sandoz: Using formatting objects with the slides dtd
      • -
    -     -     - - -- cgit v1.2.3