| <?xml version="1.0" standalone="no"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!-- $Id$ --> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> |
| <document> |
| <header> |
| <title>Standard FOP Extensions</title> |
| <version>$Revision$</version> |
| </header> |
| <body> |
| <p> |
| By "extension", we mean any data that can be placed in the input XML document that |
| is not addressed by the XSL-FO standard. |
| By having a mechanism for supporting extensions, FOP is able to add features that |
| are not covered in the specification. |
| </p> |
| <p> |
| The extensions documented here are included with FOP, and are automatically available |
| to you. If you wish to add an extension of your own to FOP, please see the |
| <a href="../dev/extensions.html">Developers' Extension Page</a>. |
| </p> |
| <note>All extensions require the correct use of an appropriate namespace in your input document.</note> |
| <section id="svg"> |
| <title>SVG</title> |
| <p> |
| Please see the <a href="graphics.html#svg">SVG documentation</a> for more details. |
| </p> |
| </section> |
| <section id="fo-extensions"> |
| <title>FO Extensions</title> |
| <section id="fox-namespace"> |
| <title>Namespace</title> |
| <p> |
| By convention, FO extensions in FOP use the "fox" namespace prefix. |
| To use any of the FO extensions, add a namespace entry for |
| <code>http://xmlgraphics.apache.org/fop/extensions</code> to the root element: |
| </p> |
| <source><![CDATA[<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" |
| xmlns:fox="http://xmlgraphics.apache.org/fop/extensions">]]></source> |
| </section> |
| <section id="bookmarks"> |
| <title>PDF Bookmarks</title> |
| <p> |
| In previous versions of Apache FOP there was a <code>fox:outline</code> element |
| which was used to create outlines in PDF files. The redesigned code makes use |
| of the new <a href="http://www.w3.org/TR/xsl11/#fo_bookmark-tree">bookmark feature defined in the latest XSL 1.1 working draft</a>. |
| </p> |
| </section> |
| <section id="named-destinations"> |
| <title>Anchors or Named Destinations</title> |
| <p>Use the fox:destination element to define "named destinations" inside a PDF document. |
| These are useful as fragment identifiers, e.g. "http://server/document.pdf#anchor-name". |
| fox:destination elements can be placed almost anywhere in the fo document, including a child of |
| root, a block-level element, or an inline-level element. |
| For the destination to actually work, it must correspond to an "id" attribute on some fo element |
| within the document. In other words, the "id" attribute actually creates the "view" within the |
| PDF document. The fox:destination simply gives that view an independent name. |
| </p> |
| <source><![CDATA[<fox:destination internal-destination="table-of-contents"/> |
| ... |
| <fo:block id="table-of-contents">Table of Contents</fo:block>]]></source> |
| <warning>It is possible that in some future release of FOP, <em>all </em>elements with |
| "id" attributes will generate named-destinations, which will eliminate the need for |
| fox:destination.</warning> |
| </section> |
| <section id="table-continue-label"> |
| <title>Table Continuation Label</title> |
| <p>This extension element hasn't been reimplemented for the redesigned code, yet.</p> |
| <!--p>Use the fox:continued-label element to create content in table-header and |
| table-footer cells that will appear only on pages after the first page that the table |
| appears. fox:continued-label is itself inline content, and is a container of fo:inline |
| content. This content will be laid out only if the table does not fit on a single page and flows |
| to following pages. Here is an example of FO code creating such a table-header:</p> |
| <source><![CDATA[<fo:table-header> |
| <fo:table-row> |
| <fo:table-cell> |
| <fo:block>Header column 1 with continued label |
| <fox:continued-label><fo:inline> (cont.)</fo:inline></fox:continued-label> |
| </fo:block> |
| </fo:table-cell> |
| <fo:table-cell> |
| <fo:block>Header column 2 with no continued label</fo:block> |
| </fo:table-cell> |
| </fo:table-row> |
| </fo:table-header>]]></source--> |
| </section> |
| <section id="widow-orphan-content-limit"> |
| <title>fox:orphan-content-limit and fox:widow-content-limit</title> |
| <p> |
| The two proprietary extension properties, fox:orphan-content-limit and |
| fox:widow-content-limit, are used to improve the layout of list-blocks and tables. |
| If you have a table with many entries, you don't want a single row to be left over |
| on a page. You will want to make sure that at least two or three lines are kept |
| together. The properties take an absolute length which specifies the area at the |
| beginning (fox:widow-content-limit) or at the end (fox:orphan-content-limit) of a |
| table or list-block. The properties are inherited and only have an effect on fo:table |
| and fo:list-block. An example: fox:widow-content-limit="3 * 1.2em" would make sure |
| the you'll have at least three lines (assuming line-height="1.2") together on a table |
| or list-block. |
| </p> |
| </section> |
| <section id="external-document"> |
| <title>fox:external-document</title> |
| <note> |
| This feature is incomplete. Support for multi-page documents will be added shortly. |
| At the moment, only single-page images will work. And this will not work with RTF output. |
| </note> |
| <p> |
| This is a proprietary extension element which allows to add whole images as pages to |
| an FO document. For example, if you have a scanned document or a fax as multi-page TIFF |
| file, you can append or insert this document using the <code>fox:external-document</code> |
| element. Each page of the external document will create one full page in the target |
| format. |
| </p> |
| <p> |
| The <code>fox:external-document</code> element is structurally a peer to |
| <code>fo:page-sequence</code>, so wherever you can put an <code>fo:page-sequence</code> |
| you could also place a <code>fox:external-document</code>. |
| Therefore, the specified contents for <code>fo:root</code> change to: |
| </p> |
| <p> |
| <code> |
| (layout-master-set, declarations?, bookmark-tree?, (page-sequence|page-sequence-wrapper|fox:external-document|fox:destination)+) |
| </code> |
| </p> |
| <section> |
| <title>Specification</title> |
| <p> |
| The <code>fox:external-document</code> extension formatting object is used to specify |
| how to create a (sub-)sequence of pages within a document. The content of these pages |
| comes from the individual subimages/pages of an image or paged document (for example: |
| multi-page TIFF in the form of faxes or scanned documents, or PDF files). The |
| formatting object creates the necessary areas to display one image per page. |
| </p> |
| <p> |
| In terms of page numbers, the behaviour is the same as for |
| <code>fo:page-sequence</code>. The placement of the image inside the page is similar |
| to that of <code>fo:external-graphic</code> or <code>fo:instream-foreign-object</code>, |
| i.e. the viewport (and therefore the page size) is defined by either the intrinsic |
| size of the image or by the size properties that apply to this formatting object. |
| </p> |
| <p>Content: EMPTY</p> |
| <p>The following properties apply to this formatting object:</p> |
| <ul> |
| <li>(Common Accessibility Properties) (not implemented, yet)</li> |
| <li>(Common Aural Properties) (not implemented, yet)</li> |
| <li>block-progression-dimension</li> |
| <li>content-height</li> |
| <li>content-type</li> |
| <li>content-width</li> |
| <li>display-align</li> |
| <li>height</li> |
| <li>id</li> |
| <li>inline-progression-dimension</li> |
| <li>overflow</li> |
| <li>pages: <page-set> (see below) (not implemented, yet)</li> |
| <li>reference-orientation</li> |
| <li>scaling</li> |
| <li>scaling-method</li> |
| <li>src</li> |
| <li>text-align</li> |
| <li>width</li> |
| </ul> |
| <p> |
| Datatype "page-set": Value: auto | <integer-range>, |
| Default: "auto" which means all pages/subimages of the document. |
| <integer-range> allows values such as "7" or "1-3" |
| </p> |
| <note> |
| <code>fox:external-document</code> is not suitable for concatenating FO documents. |
| For this, XInclude is recommended. |
| </note> |
| </section> |
| </section> |
| <section id="transform"> |
| <title>Free-form Transformation for fo:block-container</title> |
| <p> |
| For <code>fo:block-container</code> elements whose <code>absolute-position</code> set to |
| "absolute" or "fixed" you can use the extension attribute <code>fox:transform</code> |
| to apply a free-form transformation to the whole block-container. The content of the |
| <code>fox:transform</code> attribute is the same as for |
| <a href="http://www.w3.org/TR/SVG/coords.html#TransformAttribute">SVG's transform attribute</a>. |
| The transformation specified here is performed in addition to other implicit |
| transformations of the block-container (resulting from top, left and other properties) |
| and after them. |
| </p> |
| <p> |
| Examples: <code>fox:transform="rotate(45)"</code> would rotate the block-container |
| by 45 degrees clock-wise around its upper-left corner. |
| <code>fox:transform="translate(10000,0)"</code> would move the block-container to the |
| right by 10 points (=10000 millipoints, FOP uses millipoints internally!). |
| </p> |
| <note> |
| This extension attribute doesn't work for all output formats! It's currently only |
| supported for PDF, PS and Java2D-based renderers. |
| </note> |
| </section> |
| <section id="color-functions"> |
| <title>Color functions</title> |
| <p> |
| XSL-FO supports specifying color using the rgb(), rgb-icc() and system-color() functions. |
| Apache FOP provides additional color functions for special use cases. Please note that |
| using these functions compromises the interoperability of an FO document. |
| </p> |
| <section id="color-function-cmyk"> |
| <title>cmyk()</title> |
| <p><code>color cmyk(numeric, numeric, numeric, numeric)</code></p> |
| <p> |
| This function will construct a color in device-specific CMYK color space. The numbers |
| must be between 0.0 and 1.0. For output formats that don't support device-specific |
| color space the CMYK value is converted to an sRGB value. |
| </p> |
| </section> |
| </section> |
| |
| </section> |
| </body> |
| </document> |
| |
