Some consolidation of information about page-sequence-master and simple-page-master; removal of basic1.fo (not informative, also duplicated elsewhere.)

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

7 files changed, 30 insertions, 172 deletions

diff --git a/examples/fo/basic/bordershorthand.fo b/examples/fo/basic/bordershorthand.fo
index 6c5282846..e90580de5 100644
--- a/examples/fo/basic/bordershorthand.fo
+++ b/examples/fo/basic/bordershorthand.fo
@@ -10,15 +10,6 @@ Below fo:root there is always
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <fo:layout-master-set>
-  <!-- fo:layout-master-set defines in its children the page layout:
-       the pagination and layout specifications
-       - page-masters: have the role of describing the intended subdivisions
-                       of a page and the geometry of these subdivisions
-       - page-sequence-masters: have the role of describing the sequence
-                                of page-masters that will be used to generate
-                                pages during the formatting of an fo:page-sequence
-
-  -->
 
     <!-- layout for the first page -->
     <fo:simple-page-master master-name="first"
@@ -46,16 +37,16 @@ Below fo:root there is always
       <fo:region-after extent="1.5cm"/>
     </fo:simple-page-master>
 
-<fo:page-sequence-master master-name="basicPSM" >
-  <fo:repeatable-page-master-alternatives>
-    <fo:conditional-page-master-reference master-reference="first"
-      page-position="first" />
-    <fo:conditional-page-master-reference master-reference="rest"
-      page-position="rest" />
-    <!-- recommended fallback procedure -->
-    <fo:conditional-page-master-reference master-reference="rest" />
-  </fo:repeatable-page-master-alternatives>
-</fo:page-sequence-master>
+    <fo:page-sequence-master master-name="basicPSM" >
+      <fo:repeatable-page-master-alternatives>
+        <fo:conditional-page-master-reference master-reference="first"
+          page-position="first" />
+        <fo:conditional-page-master-reference master-reference="rest"
+          page-position="rest" />
+        <!-- recommended fallback procedure -->
+        <fo:conditional-page-master-reference master-reference="rest" />
+      </fo:repeatable-page-master-alternatives>
+    </fo:page-sequence-master>
 
   </fo:layout-master-set>
   <!-- end: defines page layout -->
diff --git a/examples/fo/basic/corresprop.fo b/examples/fo/basic/corresprop.fo
index 565e35fe5..ea5e2889e 100644
--- a/examples/fo/basic/corresprop.fo
+++ b/examples/fo/basic/corresprop.fo
@@ -10,15 +10,6 @@ Below fo:root there is always
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <fo:layout-master-set>
-  <!-- fo:layout-master-set defines in its children the page layout:
-       the pagination and layout specifications
-       - page-masters: have the role of describing the intended subdivisions
-                       of a page and the geometry of these subdivisions
-       - page-sequence-masters: have the role of describing the sequence
-                                of page-masters that will be used to generate
-                                pages during the formatting of an fo:page-sequence
-
-  -->
 
     <!-- layout for the first page -->
     <fo:simple-page-master master-name="first"
diff --git a/examples/fo/basic/inhprop.fo b/examples/fo/basic/inhprop.fo
index 766c3b694..8caf68fc5 100644
--- a/examples/fo/basic/inhprop.fo
+++ b/examples/fo/basic/inhprop.fo
@@ -10,15 +10,6 @@ Below fo:root there is always
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <fo:layout-master-set>
-  <!-- fo:layout-master-set defines in its children the page layout:
-       the pagination and layout specifications
-       - page-masters: have the role of describing the intended subdivisions
-                       of a page and the geometry of these subdivisions
-       - page-sequence-masters: have the role of describing the sequence
-                                of page-masters that will be used to generate
-                                pages during the formatting of an fo:page-sequence
-
-  -->
 
     <!-- layout for the first page -->
     <fo:simple-page-master master-name="first"
diff --git a/examples/fo/basic/normal.fo b/examples/fo/basic/normal.fo
index f3d5e0e36..773628277 100644
--- a/examples/fo/basic/normal.fo
+++ b/examples/fo/basic/normal.fo
@@ -10,15 +10,6 @@ Below fo:root there is always
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <fo:layout-master-set>
-  <!-- fo:layout-master-set defines in its children the page layout:
-       the pagination and layout specifications
-       - page-masters: have the role of describing the intended subdivisions
-                       of a page and the geometry of these subdivisions
-       - page-sequence-masters: have the role of describing the sequence
-                                of page-masters that will be used to generate
-                                pages during the formatting of an fo:page-sequence
-
-  -->
 
     <!-- layout for the first page -->
     <fo:simple-page-master master-name="first"
diff --git a/examples/fo/basic/normalex.fo b/examples/fo/basic/normalex.fo
index 111d6013a..0ea0f8991 100644
--- a/examples/fo/basic/normalex.fo
+++ b/examples/fo/basic/normalex.fo
@@ -10,15 +10,6 @@ Below fo:root there is always
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <fo:layout-master-set>
-  <!-- fo:layout-master-set defines in its children the page layout:
-       the pagination and layout specifications
-       - page-masters: have the role of describing the intended subdivisions
-                       of a page and the geometry of these subdivisions
-       - page-sequence-masters: have the role of describing the sequence
-                                of page-masters that will be used to generate
-                                pages during the formatting of an fo:page-sequence
-
-  -->
 
     <!-- layout for the first page -->
     <fo:simple-page-master master-name="first"
diff --git a/examples/fo/pagination/basic1.fo b/examples/fo/pagination/basic1.fo
deleted file mode 100644
index 031b52a1e..000000000
--- a/examples/fo/pagination/basic1.fo
+++ /dev/null
@@ -1,112 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-
-<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
-
-  <!-- defines page layout -->
-  <fo:layout-master-set>
-
-    <!-- layout for the first page -->
-    <fo:simple-page-master master-name="only"
-                  page-height="29.7cm"
-                  page-width="21cm"
-                  margin-top="1cm"
-                  margin-bottom="2cm"
-                  margin-left="2.5cm"
-                  margin-right="2.5cm">
-      <fo:region-body margin-top="3cm"/>
-      <fo:region-before extent="3cm"/>
-      <fo:region-after extent="1.5cm"/>
-    </fo:simple-page-master>
-
-  </fo:layout-master-set>
-  <!-- end: defines page layout -->
-
-  <!-- actual layout -->
-  <fo:page-sequence master-reference="only" initial-page-number="1">
-
-    <!-- usage of page layout -->
-    <!-- header -->
-    <fo:static-content flow-name="xsl-region-before">
-      <fo:block text-align="end"
-            font-size="10pt"
-            font-family="serif"
-            line-height="14pt" >
-        XML Recommendation - p. <fo:page-number/>
-      </fo:block>
-    </fo:static-content>
-
-    <fo:flow flow-name="xsl-region-body">
-
-      <!-- defines text title level 1-->
-      <fo:block font-size="18pt"
-            font-family="sans-serif"
-            line-height="24pt"
-            space-after.optimum="15pt"
-            background-color="blue"
-            color="white"
-            text-align="center"
-            padding-top="0pt">
-        Extensible Markup Language (XML) 1.0
-      </fo:block>
-
-      <!-- defines text title level 2-->
-      <fo:block font-size="16pt"
-            font-family="sans-serif"
-            line-height="20pt"
-            space-before.optimum="10pt"
-            space-after.optimum="10pt"
-            text-align="start"
-            padding-top="0pt">
-        Abstract
-      </fo:block>
-
-      <!-- Normal text -->
-      <fo:block font-size="12pt"
-                font-family="sans-serif"
-                line-height="15pt"
-                space-after.optimum="3pt"
-                text-align="start">
-        The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to
-        enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML
-        has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information
-        go to <fo:basic-link external-destination="normal.pdf">normal.pdf</fo:basic-link>
-      </fo:block>
-
-      <!-- defines text title level 2-->
-      <fo:block font-size="16pt"
-            font-family="sans-serif"
-            line-height="20pt"
-            space-before.optimum="10pt"
-            space-after.optimum="10pt"
-            text-align="start"
-            padding-top="0pt">
-        Status of this document
-      </fo:block>
-
-      <!-- Normal text -->
-      <fo:block font-size="12pt"
-                font-family="sans-serif"
-                line-height="15pt"
-                space-after.optimum="3pt"
-                text-align="start">
-        This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a
-        W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from
-        another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its
-        widespread deployment. This enhances the functionality and interoperability of the Web. For further information go to
-        <fo:basic-link external-destination="normal.pdf">normal.pdf</fo:basic-link>
-      </fo:block>
-
-      <!-- Normal text -->
-      <fo:block font-size="12pt"
-                font-family="sans-serif"
-                line-height="15pt"
-                space-after.optimum="3pt"
-                text-align="start">
-        This document specifies a syntax created by subsetting an existing, widely used international text processing standard
-        (Standard Generalized Markup Language, ISO 8879:1986(E) as amended and corrected) for use on the World Wide Web. It
-        is a product of the W3C XML Activity, details of which can be found at http://www.w3.org/XML. A list of current W3C
-        Recommendations and other technical documents can be found at http://www.w3.org/TR.
-      </fo:block>
-    </fo:flow>
-  </fo:page-sequence>
-</fo:root>
diff --git a/examples/fo/pagination/basic2.fo b/examples/fo/pagination/basic2.fo
index 214f43b8f..3b268d3c2 100644
--- a/examples/fo/pagination/basic2.fo
+++ b/examples/fo/pagination/basic2.fo
@@ -1,12 +1,26 @@
 <?xml version="1.0" encoding="utf-8"?>
 
+<!-- This example shows the simplest use of an fo:page-sequence-master (PSM), 
+    having only a single fo:simple-page-master-reference.
+    
+    Note that because only a single fo:simple-page-master-reference is being
+    used, this PSM can actually be omitted.  Instead, the fo:page-sequence's 
+    master-reference can be set directly to the master-name attribute 
+    ("SPM_Name") of the fo:simple-page-master (SPM).
+    
+    Also note that using a single fo:single-page-master-reference (as opposed 
+    to a fo:repeatable-page-master-reference) within the PSM limits you 
+    to one (1) page for the referencing fo:page-sequence.  If the fo:page-sequence's
+    master-reference is set to the master-name of the SPM, however, the number
+    of pages that can be output using that SPM is unbounded.
+-->
 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
 
   <!-- defines page layout -->
   <fo:layout-master-set>
 
     <!-- layout for the first page -->
-    <fo:simple-page-master master-name="only"
+    <fo:simple-page-master master-name="SPM_Name"
                   page-height="29.7cm"
                   page-width="21cm"
                   margin-top="1cm"
@@ -18,14 +32,15 @@
       <fo:region-after extent="1.5cm"/>
     </fo:simple-page-master>
 
-  <fo:page-sequence-master master-name="single">
-    <fo:single-page-master-reference master-reference="only"/>
+  <fo:page-sequence-master master-name="PSM_Name">
+    <fo:single-page-master-reference master-reference="SPM_Name"/>
   </fo:page-sequence-master>
   </fo:layout-master-set>
   <!-- end: defines page layout -->
 
-  <!-- actual layout -->
-  <fo:page-sequence master-reference="single" initial-page-number="1">
+  <!-- actual layout, note master-reference can alternatively be set to
+       SPM_Name as mentioned above -->
+  <fo:page-sequence master-reference="PSM_Name" initial-page-number="1">
 
     <!-- usage of page layout -->
     <!-- header -->