Added new extension element: fox:external-document. It allows to add whole documents such as multi-page TIFF images to be inserted as peers to a page-sequence. Each image will make up an entire page. See the documentation for details. ATM, only single pages are possible. Multi-page images will be supported with the new image package.

Some preparations for page-position="only" but the implementation is incomplete and "only" has no effect, yet. (Just uploaded some stuff I once started)
Some javadoc cleanups.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@607032 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 73 insertions, 0 deletions

diff --git a/src/documentation/content/xdocs/trunk/extensions.xml b/src/documentation/content/xdocs/trunk/extensions.xml
index dd4a79535..288695286 100644
--- a/src/documentation/content/xdocs/trunk/extensions.xml
+++ b/src/documentation/content/xdocs/trunk/extensions.xml
@@ -115,6 +115,79 @@ to following pages. Here is an example of FO code creating such a table-header:<
           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)+)
+          </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>
   </body>
 </document>