src/documentation/content/xdocs/0.95/extensions.xml - xmlgraphics-fop - Git at Google


            
            <?xml version="1.0" encoding="UTF-8" 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 Apache™ 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: &lt;page-set&gt; (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 | &lt;integer-range&gt;,

            
                        Default: "auto" which means all pages/subimages of the document.

            
                        &lt;integer-range&gt; 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>
	<?xml version="1.0" encoding="UTF-8" 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 Apache™ 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>