From b15d38da94b6edb8460c824a38ad42ac5fe9a37a Mon Sep 17 00:00:00 2001 From: fotis Date: Fri, 23 Jun 2000 13:16:43 +0000 Subject: [PATCH] add: xml files with the fop documentation (mirrors files from xml-site) and an ant script to write all into one pdf file git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@193436 13f79535-47bb-0310-9956-ffa450edef68 --- docs/xml-docs/build.xml | 76 ++++++++ docs/xml-docs/fop.xml | 26 +++ docs/xml-docs/fop/architecture.xml | 257 +++++++++++++++++++++++++ docs/xml-docs/fop/bugs.xml | 20 ++ docs/xml-docs/fop/compiling.xml | 61 ++++++ docs/xml-docs/fop/download.xml | 17 ++ docs/xml-docs/fop/embedding.xml | 42 +++++ docs/xml-docs/fop/examples.xml | 30 +++ docs/xml-docs/fop/faq.xml | 77 ++++++++ docs/xml-docs/fop/implemented.xml | 148 +++++++++++++++ docs/xml-docs/fop/involved.xml | 55 ++++++ docs/xml-docs/fop/license.xml | 57 ++++++ docs/xml-docs/fop/limitations.xml | 74 ++++++++ docs/xml-docs/fop/readme.xml | 60 ++++++ docs/xml-docs/fop/running.xml | 105 +++++++++++ docs/xml-docs/fop/specs.xml | 18 ++ docs/xml-docs/makedoc.bat | 26 +++ docs/xml-docs/readme | 10 + docs/xml-docs/xml2pdf.xsl | 290 +++++++++++++++++++++++++++++ 19 files changed, 1449 insertions(+) create mode 100644 docs/xml-docs/build.xml create mode 100644 docs/xml-docs/fop.xml create mode 100644 docs/xml-docs/fop/architecture.xml create mode 100644 docs/xml-docs/fop/bugs.xml create mode 100644 docs/xml-docs/fop/compiling.xml create mode 100644 docs/xml-docs/fop/download.xml create mode 100644 docs/xml-docs/fop/embedding.xml create mode 100644 docs/xml-docs/fop/examples.xml create mode 100644 docs/xml-docs/fop/faq.xml create mode 100644 docs/xml-docs/fop/implemented.xml create mode 100644 docs/xml-docs/fop/involved.xml create mode 100644 docs/xml-docs/fop/license.xml create mode 100644 docs/xml-docs/fop/limitations.xml create mode 100644 docs/xml-docs/fop/readme.xml create mode 100644 docs/xml-docs/fop/running.xml create mode 100644 docs/xml-docs/fop/specs.xml create mode 100755 docs/xml-docs/makedoc.bat create mode 100644 docs/xml-docs/readme create mode 100644 docs/xml-docs/xml2pdf.xsl diff --git a/docs/xml-docs/build.xml b/docs/xml-docs/build.xml new file mode 100644 index 000000000..c8ea036e6 --- /dev/null +++ b/docs/xml-docs/build.xml @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/xml-docs/fop.xml b/docs/xml-docs/fop.xml new file mode 100644 index 000000000..4889db954 --- /dev/null +++ b/docs/xml-docs/fop.xml @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/xml-docs/fop/architecture.xml b/docs/xml-docs/fop/architecture.xml new file mode 100644 index 000000000..06bed7ca9 --- /dev/null +++ b/docs/xml-docs/fop/architecture.xml @@ -0,0 +1,257 @@ + + + + + + + + +

+The overall process is controlled by org.apache.fop.apps.Driver. In +this class, a typical sequence is:

+ +

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.setWriter(new PrintWriter(new FileWriter(args[1])));

+

+

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

+

+

driver.format();

+

+

driver.render();

+ + + +

The class org.apache.fop.fo.FOTreeBuilder is responsible for actually +constructing the FO tree. The key SAX events used are

+

startElement(),

+

endElement() and characters().

+ +

All formatting objects derive from abstract class +org.apache.fop.fo.FONode. The other FO classes inherit from +FONode as follows:

+ +

            FONode

+

               |

+

     __________|________

+

    |                   |

+

   FObj               FOText

+

    |

+

    |___________________

+

    |                   |

+

  FObjMixed      SequenceSpecifier +

+ +

FO's extending FObj:

+ +

Package org.apache.fop.fo.pagination:

+ + +

LayoutMasterSet

+

PageSequence

+

RegionAfter

+

RegionBefore

+

RegionBody

+

Root

+

SequenceSpecification

+

SimplePageMaster

+ + +

Package org.apache.fop.fo.flow:

+ + +

BlockContainer

+

DisplayGraphic

+

DisplayRule

+

DisplaySequence

+

Flow

+

InlineGraphic

+

ListBlock

+

ListItem

+

ListItemBody

+

ListItemLabel

+

PageNumber

+

StaticContent

+

Table

+

TableBody

+

TableCell

+

TableColumn

+

TableRow

+ +

FO's extending SequenceSpecifier:

+ +

Package org.apache.fop.fo.pagination:

+ + +

SequenceSpecifierAlternating

+

SequenceSpecifierRepeating

+

SequenceSpecifierSingle

+ +

FO's extending FObjMixed:

+ +

Package org.apache.fop.fo.flow:

+ + +

Block

+

InlineSequence

+

SimpleLink

+ + + + +

+The class inheritance described above only describes the nature of the +content. Every FO in FOP also has a parent, and a Vector of children. The +parent attribute (in the Java sense), in particular, is used to enforce +constraints required by the FO hierarchy. +

+ +

+FONode, among other things, ensures that FO's have a parent, that they +have children, that they maintain a marker of where the layout was up to +(for FObj's it is the child number, and for FOText's it is the character +number), and that they have a layout() method. +

+ + + + +

+Every FO class has code that looks something like this: +

+ +

public static class Maker extends FObj.Maker {

+

   public FObj make(FObj parent, PropertyList propertyList)

+

     throws FOPException

+

   {

+

     return new SimplePageMaster(parent, propertyList);

+

   }

+

}

+ + +

+The class also has a static method that resembles +

+ +

public static FObj.Maker maker()

+

   {

+

     return new PageSequence.Maker();

+

   }

+ +

+A hash 'fobjTable' exists in FOTreeBuilder, and maps the FO names (such as +'fo:table') to object references to the appropriate factories +(such as Table.Maker). +

+ +

+Properties (recall that FO's have properties, areas have traits, and XML +nodes have attributes) are also a concern of FOTreeBuilder. It +accomplishes this by using PropertyListBuilder, which contains a hash of +property names and their respective makers. The base class for +properties is Property, and the property makers extend +Property.Maker. +

+ + + +

+FOTreeBuilder calls format() on the root FO, passing +it the AreaTree +reference. In turn, Root calls format() on each +PageSequence, passing it +the AreaTree reference. +

+ +

+The PageSequence format() method does the following things: +

+ +
    +
  1. Makes a Page, using PageMasterFactory to produce a +PageMaster, and +using makePage() in the latter class. In the simplest picture, +a Page has +5 areas represented by AreaContainers;
    2. + +
  2. Handles layout for StaticContent objects in the 'before' and 'after' +regions, if set. This uses the layout() method in +StaticContent;
    3. + +
  3. If a page break is not forced, it will continue to layout the flow into +the body area (AreaContainer) of the current page;
    4. + +
  4. It continues with (1) when layout into the current page is done, but +the flow is not empty.
    5. +
+ + + + +

+FO's that represent actual areas, starting with Flow and +StaticContent, have +a layout() method, with the following signature: +

+ +

+ + public Status layout(Area area) + +

+ +

+The fundamental role of the layout() method is to manage the layout of +children and/or to generate new areas. +

+ +

+Example: the layout() method for Flow generates no new areas - it manages the +layout of the flow children. +

+ +

+Example: the layout() method for Block +generates a new BlockArea in and of +itself, and also manages the layout of the block children, which are added +to the BlockArea before that is itself added to its parent +Area. +

+ +

+Layout() methods are subject to the general constraint that possibly not +all of their children can be accommodated, and they report back accordingly +with an appropriate Status. +

+ + + + +

+This is a separate process. The render() method in +Driver is invoked (say, +by CommandLine) with the laid-out AreaTree and a +PrintWriter as arguments. +This actually calls the render() method in a specific implementation of +the Renderer interface, typically PDFRenderer or +AWTRenderer. +

+ +

+At the highest level PDFRenderer, for example, begins by rendering each +Page. The render() method in Page (as is the case for other areas), +invokes a particular method in the renderer of choice, e.g. +renderPage(). +NOTE: this system is bypassed for Page, incidentally. +

+ +

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

+ + + \ No newline at end of file diff --git a/docs/xml-docs/fop/bugs.xml b/docs/xml-docs/fop/bugs.xml new file mode 100644 index 000000000..b1fc88b70 --- /dev/null +++ b/docs/xml-docs/fop/bugs.xml @@ -0,0 +1,20 @@ + + + + + + + + +

Please use the bug reporting system bugzilla + , which is part of xml.apache.org.

+ + +

Colour not continued onto subsequent pages, if coloured block goes over page. +

+

Each page-sequence begins its page numbering with the number 1 (unless another integer is + specified in the initial-page-number attribute). The W3C recommendations says that + the default (auto) for initial-page-number is: The first page sequence starts with 1. For any further + fo:page-sequence the initial number will be one greater than the last number for that sequence.

+ + diff --git a/docs/xml-docs/fop/compiling.xml b/docs/xml-docs/fop/compiling.xml new file mode 100644 index 000000000..e8f2f20b3 --- /dev/null +++ b/docs/xml-docs/fop/compiling.xml @@ -0,0 +1,61 @@ + + + + + + + + +

If you use Java 1.1.x you must also seperately include the swing classes, which can + be found at the + Sun website. From Java 1.2 on (aka Java 2) they are part of the standard + distribution. +

+ + +

An XML parser which supports Sax and DOM like + Xerces-J. + The parser must be in your classpath

+ + +

Some of the Java source code in FOP is generated from XML using + XSLT. Xalan must be used to generate this code.

+

Xalan is an XSL stylesheet processor written in java. At the moment you + can't use any other processor, because the make process makes use of some + proprietary features of Xalan which allow to write output in more + then one document. You can find Xalan also at + xml.apache.org. You have to use Xalan version 0.19.5 or later. + Xalan.jar must be in your classpath and also the file bsf.jar, which comes with Xalan.

+ + +

You have to set the enviroment variable JAVA_HOME. It must point to your local JDK + root directory. This is true, even if you use JDK 1.2 or above, which don't need this + setting. It is used by the compilation software.

+ + +

If you need PDFOutputHandler (an extension, which calls Fop from the XSLT processor XT) you also + must have xp.jar and xt.jar (both can be found at http://www.jclark.com/xml/ + in your classpath. +

+

A CLASSPATH for a complete compilation of Fop could look like this, if all these jar files are in + a directory called jars (example uses windows syntax): +

+

set CLASSPATH=\jars\xp.jar;\jars\xt.jar;\jars\xalan.jar;\jars\xerces.jar;\jars\bsf.jar +

+ + + +

Compilation is started by executing build, either as a batch file on win32 (build.bat) or as a shell script on unix. The compilation uses Ant, + a replacement of make (you can find more information about Ant at + jakarte.apache.org). + build.xml is the replacement of makefile. Look there for further information.

+

A help screen is shown by calling "build usage". +

+ + + +

We strongly recommend the use of Codewarrior Java. You will find + a link to more information in the near future. +

+ + diff --git a/docs/xml-docs/fop/download.xml b/docs/xml-docs/fop/download.xml new file mode 100644 index 000000000..38946d0ea --- /dev/null +++ b/docs/xml-docs/fop/download.xml @@ -0,0 +1,17 @@ + + + + + + + +

You can download the latest release version from the distribution directory.

+

The file contains also the documentation (including some example fo files) and the source.

+

To run FOP from the command line, see Running FOP. If you are + interested in embedding FOP in a Java application of your own, see + Embedding FOP. +

+ + + diff --git a/docs/xml-docs/fop/embedding.xml b/docs/xml-docs/fop/embedding.xml new file mode 100644 index 000000000..885c0f9ba --- /dev/null +++ b/docs/xml-docs/fop/embedding.xml @@ -0,0 +1,42 @@ + + + + + + + + +

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 + 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 + instantiate the class itself. The advantage of the latter is it + enables runtime determination of Renderer and ElementMapping(s). +

+

Once the Driver is set up, the buildFOTree method + is called. Depending on whether DOM or SAX is being used, the + invocation of the method is either buildFOTree(Document) or + buildFOTree(Parser, InputSource) respectively. +

+

A third possibility may be used to build the FO Tree, namely + calling getDocumentHandler() and firing the SAX events yourself. +

+

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:

+

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.setWriter(new PrintWriter(new FileWriter(args[1])));

+

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

+

driver.format();

+

driver.render();

+ + + + diff --git a/docs/xml-docs/fop/examples.xml b/docs/xml-docs/fop/examples.xml new file mode 100644 index 000000000..f8b20c8d8 --- /dev/null +++ b/docs/xml-docs/fop/examples.xml @@ -0,0 +1,30 @@ + + + + + + +

Examples for the use of xsl:fo can be found in the Fop distribution in + the subdirectory /docs/examples/fo. +

+

Please be warned: At the moment FOP only supports the + XSL Working Draft 21 April 1999 and the examples are also following this version. +

+

At the moment the following files are part of the distribution:

+ + + diff --git a/docs/xml-docs/fop/faq.xml b/docs/xml-docs/fop/faq.xml new file mode 100644 index 000000000..df0ad9eac --- /dev/null +++ b/docs/xml-docs/fop/faq.xml @@ -0,0 +1,77 @@ + + + + + + + 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 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/implemented.xml b/docs/xml-docs/fop/implemented.xml new file mode 100644 index 000000000..214c07387 --- /dev/null +++ b/docs/xml-docs/fop/implemented.xml @@ -0,0 +1,148 @@ + + + + + + + + +

The following formatting objects and properties of the xsl-fo + working draft (21 Apr 1999) are implemented. Please have also a look at the + section on limitations +

+ + +
    +
  • block
    • +
  • display-graphic
    • +
  • display-rule
    • +
  • display-sequence
    • +
  • flow
    • +
  • inline-graphic
    • +
  • inline-sequence
    • +
  • layout-master-set
    • +
  • list-block
    • +
  • list-item
    • +
  • list-item-body
    • +
  • list-item-label
    • +
  • page-number
    • +
  • page-sequence
    • +
  • region-after
    • +
  • region-before
    • +
  • region-body
    • +
  • root
    • +
  • sequence-specification
    • +
  • sequence-specifier-alternating
    • +
  • sequence-specifier-repeating
    • +
  • sequence-specifier-single
    • +
  • simple-page-master
    • +
  • static-content
    • +
  • table (minimal support)
    • +
  • table-body (minimal support)
    • +
  • table-cell (minimal support)
    • +
  • table-column (minimal support)
    • +
  • table-row (minimal support)
    • +
+ + + +
    +
  • background-color
    • +
  • border-after-color
    • +
  • border-after-style
    • +
  • border-after-width
    • +
  • border-before-color
    • +
  • border-before-style
    • +
  • border-before-width
    • +
  • border-bottom
    • +
  • border-bottom-color
    • +
  • border-bottom-style
    • +
  • border-bottom-width
    • +
  • border-color (only one value allowed)
    • +
  • border-end-color
    • +
  • border-end-style
    • +
  • border-end-width
    • +
  • border-left
    • +
  • border-left-color
    • +
  • border-left-style
    • +
  • border-left-width
    • +
  • border-right
    • +
  • border-right-color
    • +
  • border-right-style
    • +
  • border-right-width
    • +
  • border-start-color
    • +
  • border-start-style
    • +
  • border-start-width
    • +
  • border-style
    • +
  • border-top
    • +
  • border-top-color
    • +
  • border-top-style
    • +
  • border-top-width
    • +
  • border-width
    • +
  • bottom
    • +
  • break-after
    • +
  • break-before
    • +
  • color
    • +
  • column-width
    • +
  • end-indent
    • +
  • extent
    • +
  • flow-name
    • +
  • font-family
    • +
  • font-size
    • +
  • font-style
    • +
  • font-weight
    • +
  • height
    • +
  • href
    • +
  • id
    • +
  • initial-page-number
    • +
  • keep-with-next
    • +
  • left
    • +
  • line-height
    • +
  • margin-bottom (only on pages and regions)
    • +
  • margin-left (only on pages and regions)
    • +
  • margin-right (only on pages and regions)
    • +
  • margin-top (only on pages and regions)
    • +
  • padding (only one value allowed)
    • +
  • padding-after
    • +
  • padding-before
    • +
  • padding-bottom (only in conjunction with background color)
    • +
  • padding-end
    • +
  • padding-left (only in conjunction with background color)
    • +
  • padding-right (only in conjunction with background color)
    • +
  • padding-start
    • +
  • padding-top (only in conjunction with background color)
    • +
  • page-height
    • +
  • page-master-even
    • +
  • page-master-first
    • +
  • page-master-name
    • +
  • page-master-odd
    • +
  • page-master-repeating
    • +
  • page-width
    • +
  • position (allowed values: "static" (default),"relative", "absolute", fixed )
    • +
  • provisional-distance-between-starts
    • +
  • provisional-label-separation
    • +
  • right
    • +
  • rule-thickness
    • +
  • space-after.optimum
    • +
  • space-before.optimum
    • +
  • start-indent
    • +
  • text-align
    • +
  • text-align-last
    • +
  • text-indent
    • +
  • top
    • +
  • white-space-treatment
    • +
  • width
    • +
  • wrap-option
+ + + + + + + + + + + + + diff --git a/docs/xml-docs/fop/involved.xml b/docs/xml-docs/fop/involved.xml new file mode 100644 index 000000000..1850000e0 --- /dev/null +++ b/docs/xml-docs/fop/involved.xml @@ -0,0 +1,55 @@ + + + + + + + + + +

The Status file contains the list of features people are working on at the moment. + And an outline what steps are next.

+ + +

You can subscribe to fop-dev@xml.apache.org by sending an email + to fop-dev-subscribe@xml.apache.org

+

Sending bug reports and feature requests to the list is a welcome and important contribution to + developing Fop.

+

Read also the archive + of the discussion list fop-dev to get an idea of the issues being discussed.

+ + +

Between releases the newest code can be accessed via cvs. To do this you need to install a cvs + client on your computer if it is not already there. An explanation how to connect to the + Fop source repository can be found at http://xml.apache.org/cvs.html. + An introduction into cvs and the cvs manual can be found in the + reference library.

+

All changes to the code repository are annonced in a special discussion group. You can subscribe + to fop-cvs@xml.apache.org by sending an email to + 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:

+

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.

+

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

+

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

+ + +

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 + familiar with these standards. You can find their internet addresses on our website.

+ + +

A bird's eye view on the way Fop operates can be found in the document FOP Mechanics

+

If you want to extend the functionality of FOP by adding new formatting objects, you should do the following:

+

1. FO Object: Write a class which contains the description of your formatting object and put it into the package fop.fo.flow, fop.fo.pagination (if it is a property it goes to fop.fo.properties. The classes in this package are generated via an xslt stylesheet located in codegen/properties.xml)

+

2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it is a property you need to add it to fop.fo.PropertyListBuilder)

+

3. Area: Either your need can be fulfilled within one of the existing classes in fop.layout, then just add the code to handle the new fo/property or you must write a new one.

+

4. Renderer: Choose the renderer you are interested in. If you worked on an existing layout class you must add code to handle the new features to the already existing area specific method in the renderer class. Otherwise you have to add a new method.

+ + diff --git a/docs/xml-docs/fop/license.xml b/docs/xml-docs/fop/license.xml new file mode 100644 index 000000000..809c25f7f --- /dev/null +++ b/docs/xml-docs/fop/license.xml @@ -0,0 +1,57 @@ + + + + + + + +

Copyright (C) 1999 The Apache Software Foundation. All rights reserved.

+

Redistribution and use in source and binary forms, with or without modification, + are permitted provided that the following conditions are met:

+

1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +

+ +

2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. +

+ +

3. The end-user documentation included with the redistribution, if any, must + include the following acknowledgment: "This product includes software + developed by the Apache Software Foundation (http://www.apache.org/)." + Alternately, this acknowledgment may appear in the software itself, if + and wherever such third-party acknowledgments normally appear. +

+ +

4. The names "FOP" and "Apache Software Foundation" must not be used to + endorse or promote products derived from this software without prior + written permission. For written permission, please contact + apache@apache.org. +

+ +

5. Products derived from this software may not be called "Apache", nor may + "Apache" appear in their name, without prior written permission of the + Apache Software Foundation. +

+

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU- + DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +

+ +

+ This software consists of voluntary contributions made by many individuals + on behalf of the Apache Software Foundation and was originally created by + James Tauber <jtauber@jtauber.com>. For more information on the Apache + Software Foundation, please see http://www.apache.org/. +

+ + + diff --git a/docs/xml-docs/fop/limitations.xml b/docs/xml-docs/fop/limitations.xml new file mode 100644 index 000000000..dcf0a2947 --- /dev/null +++ b/docs/xml-docs/fop/limitations.xml @@ -0,0 +1,74 @@ + + + + + + + +

The main limitation at the moment is: FOP only supports the XSL working draft 21 Apr 1999, + not the latest from 27 March 2000. FOP implements the fo objects and properties listed + in features, sometimes it does so only in a limited way. +

+ + +

The fo working draft allows describes two ways to markup lists.The list-block must have as + children either: 1) pairs of fo:list-item-label and fo:list-item-body formatting objects, or + 2) fo:list-item formatting objects.

+

At the moment FOP only implements the second way. Therefore a list has a basic structure like this:

+

<fo:list-block>

+

<fo:list-item>

+

<fo:list-item-label><fo:block></fo:block></fo:list-item-label>

+

<fo:list-item-body><fo:block></fo:block></fo:list-item-body>

+

</fo:list-item>

+

</fo:list-block>

+ + +

Padding works in conjunction with indents and spaces. It is only implemented + for blocks. At the moment padding can't be used to make extra space (indents+spaces + must be used), but only to control how much the background-color extends beyond + the content rectangle. +

+ + +

There two limitations for tables: 1) FOP needs you to explicitly specify column widths + 2) Cells have to contain block-level FOs. They can't contain straight character data. +

+

A working basic example of a table looks like this:

+

<fo:table>

+

 <fo:table-column column-width="150pt"/>

+

 <fo:table-column column-width="150pt"/>

+

 <fo:table-body font-size="10pt" font-family="sans-serif">

+

  <fo:table-row>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

  </fo:table-row>

+

  <fo:table-row>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

  </fo:table-row>

+

  <fo:table-row>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

   <fo:table-cell>

+

    <fo:block>text</fo:block>

+

   </fo:table-cell>

+

  </fo:table-row>

+

 </fo:table-body>

+

</fo:table>

+ + + + + + diff --git a/docs/xml-docs/fop/readme.xml b/docs/xml-docs/fop/readme.xml new file mode 100644 index 000000000..5b5ca42d9 --- /dev/null +++ b/docs/xml-docs/fop/readme.xml @@ -0,0 +1,60 @@ + + + + + + + + + + + +

FOP is the world's first print formatter driven by XSL formatting + objects. It is a Java application that reads a formatting object + tree and then turns it into a PDF document. The formatting object + tree, can be in the form of an XML document (output by an XSLT engine + like XT or Xalan) or can be passed in memory as a DOM Document or (in + the case of XT) SAX events. +

+

FOP is part of Apache's XML project. The homepage of FOP is + http://xml.apache.org/fop. +

+ + + +

The goals of the Apache XML FOP Project are to deliver an XSL FO->PDF formatter that is compliant to at least the Basic + conformance level described in the 27 March 2000 XSL WD, and that complies with the 11 March 1999 Portable Document + Format Specification (Version 1.3) from Adobe Systems. +

+ +

Conformance to the XML 1.0 Recommendation, XSLT 1.0 Recommendation and the XML Namespaces Recommendation is + understood. Other relevant documents, such as the XPath and XLink Working Drafts, are referenced as necessary. The FOP + Project will attempt to use the latest version of evolving specifications. +

+ +

Secondary goals of the FOP Project (also, "FOP") are desirable requirements that also have a high priority. +

+ +

One secondary goal of the FOP Project is to deliver a follow-on version of the formatter that is compliant to the Extended + conformance level described in the XSL FO. Any formatting objects that cannot be translated into PDF will be explicitly + 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. +

+ +

A final secondary goal is the continued refinement of the FOP design and implementation. In particular, maintaining the + separation between formatting and rendering, continuing to support the AWT Viewer renderer (backend), and providing + new renderers, are all desirable objectives. +

+ + + + diff --git a/docs/xml-docs/fop/running.xml b/docs/xml-docs/fop/running.xml new file mode 100644 index 000000000..bf971f41b --- /dev/null +++ b/docs/xml-docs/fop/running.xml @@ -0,0 +1,105 @@ + + + + + + + +

Following software must be installed:

+

a) Java 1.1.x or later (If you want to use AWTCommandLine, you need Swing)

+

b) An XML parser which supports SAX and DOM like + Xerces-J. + (Xerces is the default xml parser)

+

c) If you have to produce the flow objects files, which are the input for FOP, + you need a transformation utility to create this files from your xml files. + Normally this is an XSLT stylesheet processor like + XT + or XALAN. +

+ + +

There are three ways to run FOP from the command line.

+

a) Batch processing formatting objects (fo) files:

+

java org.apache.fop.apps.CommandLine fo-file pdf-file

+

b) Batch processing xml files (includes production of the fo-files):

+

java org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file

+

c) Previewing the fo-file:

+

java org.apache.fop.apps.AWTCommandLine fo-file

+

Each method uses next to the fop classes other packages. The following describes + each method in detail.

+ +

One is to first use an XSLT engine to produce the formatting object tree as an + XML document and then running the class org.apache.fop.apps.CommandLine with the + formatting object file name and PDF filename as arguments. You need to set classpath + and set the used sax parser according to your enviroment +

+

Classpath settings: You will need to include FOP and your XML Parser + in your classpath and so you might invoke FOP, if Xerces-J is your xml parser: +

+

java -cp fop.jar;xerces.jar

+

org.apache.fop.apps.CommandLine fo-file pdf-file

+

If you want to use another sax parser, you will need to set the property + org.xml.sax.parser to any other SAX Parser class to use. The following example shows + the command line, if you use XP from James Clark: +

+

java -Dorg.xml.sax.parser=com.jclark.xml.sax.Driver

+

-cp fop.jar;xerces.jar;xp.jar

+

org.apache.fop.apps.CommandLine fo-file pdf-file

+

Note: The xerces jar file must be included, because xp has no dom support.

+ + +

Rather than performing transformation with an XSLT before invoking FOP, it is + possible, if you use XT as your XSLT engine, to just call FOP and have it call + XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the + source XML file name, XSL file name and PDF file name as arguments. You will + need to include XT in your classpath and so you might invoke +

+

java -cp fop.jar;xt.jar;xerces.jar

+

org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file

+

Again, if your SAX Parser is other than Xerces, you will need to set the property + org.xml.sax.parser to the SAX Parser class to use. +

+ + +

If you already produced the FO file, you can preview the results of your + transformation without using any pdf viewer by invoking FOP with the viewer + application. You will need to include FOP and your XML Parser in your classpath +

+

java -cp fop.jar;xerces.jar

+

org.apache.fop.apps.AWTCommandLine fo-file

+

The viewer uses the swing classes.

+

Note: If you are using java 2 or later (i.e. jdk 1.2. or later) you can put all + needed jar files into the subdirectory jdk1.2.x\jre\lib\ext (windows example). Then + FOP can be started without classpath: +

+

java org.apache.fop.apps.CommandLine fo-file pdf-file

+ + + + +

Ensure that you have a recent MRJ, and that you have downloaded and + unpacked the XP and SAX distributions. The xp.jar and sax.jar files work + as is on MacOS. +

+

Drag the FOP jarfile onto the JBindery icon. When the first dialog + appears, type "org.apache.fop.apps.CommandLine" in the "Class name" field. + Using UNIX syntax, type the names of the input formatting-object file and + the output PDF in the "Optional parameters" field. +

+

Click on the Classpath icon. To add the xp.jar and sax.jar files, click + the "Add .zip file" button, navigate to the file in question, and click + Open. +

+

Once both are added (the FOP jarfile will already be in the list), click + Run. A "stdout" window will appear and display FOP runtime messages. +

+ + +

If you have problems running FOP, please have a look at the + 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 new file mode 100644 index 000000000..4dcadbade --- /dev/null +++ b/docs/xml-docs/fop/specs.xml @@ -0,0 +1,18 @@ + + + + + + + + diff --git a/docs/xml-docs/makedoc.bat b/docs/xml-docs/makedoc.bat new file mode 100755 index 000000000..d1bff133a --- /dev/null +++ b/docs/xml-docs/makedoc.bat @@ -0,0 +1,26 @@ +@echo off + +echo Building Fop documentation (pdf) +echo ---------------- + +if "%JAVA_HOME%" == "" goto error + +set LOCALCLASSPATH=%JAVA_HOME%\lib\tools.jar;%JAVA_HOME%\lib\classes.zip;..\..\lib\ant.jar;..\..\lib\xml.jar;..\..\lib;..\..\build\fop.jar +set ANT_HOME=.\lib + +echo Building Fop documentation (pdf) ... + +%JAVA_HOME%\bin\java.exe -Dant.home=%ANT_HOME% -classpath %LOCALCLASSPATH%;%CLASSPATH% org.apache.tools.ant.Main %1 %2 %3 %4 %5 + +goto end + +:error + +echo ERROR: JAVA_HOME not found in your environment. +echo Please, set the JAVA_HOME variable in your environment to match the +echo location of the Java Virtual Machine you want to use. + +:end + +rem set LOCALCLASSPATH= + diff --git a/docs/xml-docs/readme b/docs/xml-docs/readme new file mode 100644 index 000000000..2b860db0d --- /dev/null +++ b/docs/xml-docs/readme @@ -0,0 +1,10 @@ +Fop documentation (xml version) + +The files in these directory contain the Fop documentation as xml files. +The directory xml-docs/fop is a mirror of the files in the cvs repository +modul 'xml-site' /sources/fop. These files are used to create the html documentation +on xml.apache.org. + +With makedoc.bat (win32) or makedoc.sh (unix) you can create a pdf file containing +the complete Fop documentation. These scripts use ant. If you have any trouble running them, +please look into build.xml in the root directory of this distribution. \ No newline at end of file diff --git a/docs/xml-docs/xml2pdf.xsl b/docs/xml-docs/xml2pdf.xsl new file mode 100644 index 000000000..f67edd58d --- /dev/null +++ b/docs/xml-docs/xml2pdf.xsl @@ -0,0 +1,290 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FOP documentation - p. + + + + + + + + FOP - an xsl:fo renderer + + + + + + + Content + + + + + + + + + + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + · + + + + + + + + + + + + + -- 2.39.5