--- a/.hgignore	Sat Apr 27 22:27:41 2013 +0100
+++ b/.hgignore	Sat Apr 27 22:29:14 2013 +0100
@@ -1,2 +1,3 @@
 FOPRunXSLTExt/build
 FOPRunXSLTExt/dist
+FOPRunXSLTExt/examples/out

--- a/FOPRunXSLTExt/examples/README	Sat Apr 27 22:27:41 2013 +0100
+++ b/FOPRunXSLTExt/examples/README	Sat Apr 27 22:29:14 2013 +0100
@@ -15,7 +15,10 @@
 the public-ppl@w3.org mailing list.
 
 FOPRunXSLTExt is written in Java and uses the Apache FOP XSL formatter
-to produce the area trees
+to produce the area trees.
+
+INSTALLATION
+============
 
 Prerequisites:
 
@@ -62,10 +65,54 @@
 2. Because of the code the saxon9he.jar must be included always; if compiling for Xalan make sure that the Xalan JARs
 are first in order, other way around for Saxon. The errors will alert you when you run the extension.
 
-3. Examples - example XSLT stylesheets and shell scripts are provided for the two
-possibilities above.
+EXAMPLES
+========
 
-./runsaxon9he_fop10.sh example1.xml example1_saxon9_fop10.xsl out/example1_saxon9_fop10.url out example1_saxon9_fop10.if
+Example 1 - Area tree
+---------------------
 
-./runxalan_fop10.sh example1.xml example1_xalan_fop10.xsl out/example1_xalan_fop10.url out example1_xalan_fop10.if
+Produces an area tree in 'out/example1_saxon9_fop10.at'.
 
+Windows:
+
+runsaxon9he_fop10.bat example1.xml example1_saxon9_fop10.xsl out/example1_saxon9_fop10.if out example1_saxon9_fop10.at
+
+Linux/Mac:
+
+./runsaxon9he_fop10.sh example1.xml example1_saxon9_fop10.xsl out/example1_saxon9_fop10.url out example1_saxon9_fop10.at
+
+./runxalan_fop10.sh example1.xml example1_xalan_fop10.xsl out/example1_xalan_fop10.url out example1_xalan_fop10.at
+
+
+Example 3 - Rotate wide block
+-----------------------------
+
+Rotates a fixed-size box if it is too wide for the page.
+
+The <box> element in 'example3.xml' specifies its formatted height and
+width:
+
+   <box id="box001" width="8in" height="5in">
+
+With those dimensions, if you transform 'example3.xml' with
+'formatting.xsl' and format the result, the box is wider than the
+width of the page and some of the text is lost.
+
+If you transform 'example3.xml' with 'example3_saxon9_fop10.xsl',
+which uses the extension function to make an area tree during the
+transform and makes decisions based on formatted areas, the box is
+rotated when it is too wide for the page.
+
+Run the example using one of the command lines below then then run an
+XSL formatter on 'out/example3_saxon9_fop10.fo' to see the result.
+
+You can change the box/@width value in 'example3.xml' and run it again
+to see whether or not the box is rotated.
+
+Windows:
+
+runsaxon9he_fop10.bat example3.xml example3_saxon9_fop10.xsl out/example3_saxon9_fop10.fo out example3_saxon9_fop10.at
+
+Linux/Mac:
+
+./runsaxon9he_fop10.sh example3.xml example3_saxon9_fop10.xsl out/example3_saxon9_fop10.fo out example3_saxon9_fop10.at

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FOPRunXSLTExt/examples/example3.xml	Sat Apr 27 22:29:14 2013 +0100
@@ -0,0 +1,8 @@
+<example name="Example 1">
+<header>Print and Page Layout Community Group</header>
+
+<box id="box001" width="8in" height="5in">
+<paragraph id="para001">The Print and Page Layout Community Group is the "virtual water cooler" where you can hang out and discuss XSL-FO and related page layout technologies.
+</paragraph>
+</box>
+</example>

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FOPRunXSLTExt/examples/example3_saxon9_fop10.xsl	Sat Apr 27 22:29:14 2013 +0100
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================= -->
+<!-- FOPRunXSLTExt Saxon example 3                                 -->
+<!--                                                               -->
+<!-- See http://www.w3.org/community/ppl/wiki/FOPRunXSLTExt        -->
+<!--                                                               -->
+<!-- Requires Saxon 9.4 or later and FOP 1.0                       -->
+<!--                                                               -->
+<!-- Produced by the Print and Page Layout Community Group @ W3C   -->
+<!-- ============================================================= -->
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+    version="2.0"
+    xmlns:fo="http://www.w3.org/1999/XSL/Format"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    xmlns:runfop="http://org.w3c.ppl.xslt/saxon-extension"
+    exclude-result-prefixes="xs runfop">
+
+<!-- Common templates for formatting FOPRunXSLTExt examples -->
+<xsl:import href="formatting.xsl" />
+
+<xsl:key name="boxes" match="box" use="true()" />
+
+<xsl:key name="blocks" match="block[exists(@prod-id)]" use="@prod-id" />
+
+<!-- Where to write the output files. -->
+<xsl:param name="dest_dir" select="out" as="xs:string"/>
+<xsl:param name="area_tree_filename" />
+
+<!-- Initial template -->
+<xsl:template name="main">
+  <!-- Save the FO tree in a variable. -->
+  <xsl:variable name="fo_tree">
+    <xsl:apply-templates select="/" />
+  </xsl:variable>
+
+  <xsl:variable name="area_tree_file"
+		select="concat($dest_dir, '/', $area_tree_filename)" />
+
+  <xsl:message>Area tree filename = <xsl:value-of select="$area_tree_file" /></xsl:message>
+
+  <xsl:variable
+      name="url"
+      select="runfop:area-tree-url($fo_tree, $area_tree_file)"
+      as="xs:string" />
+
+  <xsl:variable
+      name="area-tree"
+      select="document($url)"
+      as="document-node()?" />
+
+  <xsl:variable name="overrides">
+    <overrides>
+      <xsl:for-each select="key('boxes', true())">
+	<xsl:variable name="id" select="@id" as="xs:string" />
+	<xsl:variable name="block"
+		      select="key('blocks', $id, $area-tree)[1]" />
+	<xsl:if test="$block/@ipd > $block/ancestor::flow/@ipd">
+	  <override id="{$id}" rotate="yes" />
+	</xsl:if>
+      </xsl:for-each>
+    </overrides>
+  </xsl:variable>
+
+  <xsl:apply-templates select="/">
+    <xsl:with-param name="overrides" select="$overrides" as="document-node()" tunnel="yes" />
+  </xsl:apply-templates>
+</xsl:template>
+
+</xsl:stylesheet>
\ No newline at end of file

--- a/FOPRunXSLTExt/examples/formatting.xsl	Sat Apr 27 22:27:41 2013 +0100
+++ b/FOPRunXSLTExt/examples/formatting.xsl	Sat Apr 27 22:29:14 2013 +0100
@@ -15,6 +15,12 @@
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     exclude-result-prefixes="xs">
 
+<xsl:key name="overrides" match="override" use="@id" />
+
+<xsl:variable name="overrides">
+  <no-overrides/>
+</xsl:variable>
+
 <xsl:template match="/">
   <fo:root>
     <fo:layout-master-set>
@@ -38,6 +44,18 @@
   </fo:block>
 </xsl:template>
 
+<xsl:template match="box">
+  <xsl:param name="overrides" select="$overrides" as="document-node()" tunnel="yes"/>
+  <fo:block-container role="{local-name()}" border="medium solid black"
+	    width="{@width}" height="{@height}" padding="12pt"
+	    id="{@id}">
+    <xsl:if test="key('overrides', @id, $overrides)/@rotate = 'yes'">
+      <xsl:attribute name="reference-orientation" select="'270'" />
+    </xsl:if>
+    <xsl:apply-templates/>
+  </fo:block-container>
+</xsl:template>
+
 <xsl:template match="paragraph">
   <fo:block id="{@id}" text-indent="5mm"
 	    font-family="verdana, sans-serif" font-size="12pt">