Trying to clear up afp:include-page-segment as there are questions every now and then.

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

1 files changed, 11 insertions, 0 deletions

diff --git a/src/documentation/content/xdocs/trunk/output.xml b/src/documentation/content/xdocs/trunk/output.xml
index 9c88c27d0..0ae9d586b 100644
--- a/src/documentation/content/xdocs/trunk/output.xml
+++ b/src/documentation/content/xdocs/trunk/output.xml
@@ -796,6 +796,17 @@ out = proc.getOutputStream();]]></source>
         fo:external-graphic elements and if it is identical (string matching is used) in the generated
         AFP the external graphic is replaced by a reference to the given resource.
         </p>
+        <p>
+          The effect here is that whenever FOP encounters the URI specified in the extension,
+          it will effectively generate code to include the page segment with the given name
+          instead of embedding the image referenced by the URI. The URI is still required as
+          the underlying image serves as a provider for the intrinsic size of the image
+          (At the moment, FOP is unable to extract the intrinsic size of the page segment from
+          an AFP resource file). For the image to appear in an AFP viewer or to be printed, the
+          AFP resource must be available on the target device. FOP does not embed the page
+          segment in the generated file. Please also note that page segments cannot be scaled.
+          They are always rendered in their intrinsic size.
+        </p>
       </section>
       <section id="afp-tag-logical-element">
         <title>Tag Logical Element (TLE) Extension</title>