7.2 Content definition

7.2.1 Flowed content vs. static content

The flow, the headers, and the footers are defined by assigning content to the region name , not to the region position.

• The page's geometry defines at which position (if any) a named region is on the page.

• Regions are just well-defined areas of the page into which content can be placed.

• Regions have default names but can be renamed .

  • The same names can be used for the same regions in different page definitions.

• The content of flows, headers, and footers is placed into regions by the region name.

Flowed content triggers the pages to be produced from a page-sequence .

• Each page-sequence construct must have exactly one flow specified.

  • A flow must indicate the region (by name) to which the content is targeted .

• Flowed content fills a region (any region) until the region overflows.

  • The overflow property dictates whether another page is generated to create a new region.

  • You can choose to signal an error on overflow.

• A page geometry in the page sequence need not have the named region accepting the flow.

  • Such a page is produced using only static content for the regions named on the page definition.

  • The next page is obtained from the page sequence and examined for the named region accepting the flow.

The formatter generates a page using the next page geometry in the page sequence.

• The amount of the flowed content dictates how many pages get generated for the sequence.

• The page geometry or pattern of page geometries dictate which regions are there on each generated page to accommodate the flow.

Static content is repeated in the named regions that appear on each generated page.

• static-content is used to define static content.

• Each page-sequence construct may have any number of static content specifications.

  • You must indicate the region (by name) to which the content is targeted.

• It is common to include a page-number object in the static content.

  • It generates a sequence of glyph areas reflecting the page number.

  • The choice in glyphs used in the generated areas is governed by properties of the page-sequence object.

    • Formal definition of these properties comes from XSLT.

  • The generated areas inherit properties ancestral to the referencing object, not the referred object.

Flowed and static content are defined on a page sequence basis.

• Every page sequence must have its own definitions of flowed content and static content.

  • It cannot point to another page sequence's content.

• flow and static-content constructs are children of the page-sequence construct.

It is not an error when content is defined for a named region and that region is not present on the page being generated.

• Nothing is rendered from the definition of the flowed content.

• If there is no region for the flowed content, the static content (if any) is rendered and a new page is generated.

• Consider the example where one interleaves pages of normally flowed content with pages entirely made of static content displaying a set of ruled lines; the resulting publication is in a workbook-like format where the pages opposite to the material are used for keeping notes.

It is a common requirement for different pages to have different static content.

• Consider the need for rendering page numbers on alternate sides of the footer

  • on the right side of odd pages,

  • on the left side of even pages.

• Use different region names for the same regions on different pages.

  • The odd page region-after constructs could be named " footer-odd " .

  • The even page region-after constructs could be named " footer-even " .

  • The page sequence would then define two different static-content constructs.

    • The construct flowed to the region named " footer-odd " would place the page number on the right.

    • The construct flowed to the region named " footer-even " would place the page number on the left.

It is a common requirement for different pages to have the same content in different places.

• Consider the need for rendering information in the outside edge of all pages.

  • Here, the content is the same but it must use the right side on odd pages and the left side on even pages.

• You cannot use the same region name for different regions on different pages.

  • Each time you use a given custom name in the set of page geometries, it must always be for the same body or perimeter region wherever else that name is used in other page geometries.

• You must duplicate the content if there are two differently named regions in two page geometries in order to obtain identical results.

  • The odd pages' region-end construct could be named " outside-odd " .

  • The even pages' region-start construct could be named " outside-even " .

  • The page sequence would define two identical static-content constructs to get the same appearance in both regions.

  • The same results would be better obtained by using the same region names in the two geometries.

It is the author's responsibility to supply in each page sequence the definitions of all content desired for the possible regions triggered by the sequence of pages.

• Stylesheets are often repetitive in order to satisfy this requirement.

7.2.2 The static-content object

Purpose

• This is the definition of content that is primarily unchanged from page to page in a page sequence.

Content

• ( 6.4.19 ) ( %block;+),

• child object:

  • %block; ( 6.2 ; 69),

• referring object:

  • page-sequence ( 6.4.5 ; 65).

Required property

• flow-name ( 7.25.5 ; 376).

Excerpts from a draft of a training rendition of this material are shown in Example 7-2.

Example 7-2 Static content definition of regions

 Line 01 <page-sequence id="fo_region-before" master-reference="frames">      02  <static-content flow-name="pages-before" font-style="italic">  03     <block text-align="center">Practical Formatting       04 Using XSL-FO</block>  </static-content>  05  <static-content flow-name="pages-after-right"  06  font-style="italic" font-size="9pt">  07     <table>...<block text-align="start">Slide 173 of       08 287 <inline font-size="8pt">&lt;frame_static-content&gt;</inline      09 ></block>...<block text-align="center">      10               <inline font-size="8pt" font-style="normal"      11 >Information subject to restrictive legend on title page.</inline>      12             </block>...      13             <block text-align="end">Page  <page-number/>  of       14 <page-number-citation ref-id="N0"/></block>...      15     </table>  </static-content>  16  <static-content flow-name="pages-after-left"  17  font-style="italic" font-size="9pt">  18     <table>...<block text-align="start">Page  <page-number/>  of       19 <page-number-citation ref-id="N0"/></block>...      20               <block text-align="center">      21                 <inline font-size="8pt" font-style="normal"      22 >Information subject to restrictive legend on title page.</inline>      23               </block>...      24               <block text-align="end"><inline       25 font-size="8pt">&lt;frame_static-content&gt;</inline> Slide 173 of       26 287</block>...</table>  </static-content>  27   <flow>... 

Of note:

• the header is a single centered title;

• two footers are defined, one for the right-hand pages and the other for the left-hand pages;

  • the right-hand footer has the page number on the right-hand side of the page;

  • the left-hand footer has the page number on the left-hand side of the page;

• each footer is a table of three columns ;

  • the start-side column is aligned to the start edge;

  • the center column is aligned at the center;

  • the end-side column is aligned to the end edge.

7.2.3 The page-number object

Purpose

• This is an inline-level placeholder replaced with the page number of the current page.

• The formatter supplies the glyphs to be inserted into the flow as character objects.

  • The glyphs used by the formatter are specified by the format property of the page-sequence for the page.

Content

• ( 6.6.10 ) EMPTY .

Property sets

• Common accessibility properties ( 7.4 ; 326),

• common aural properties ( 7.6 ; 327),

• common border, padding, and background properties ( 7.7 ; 328),

• common font properties ( 7.8 ; 331),

• common margin properties inline ( 7.11 ; 333),

• common relative position properties ( 7.12 ; 333).

Other optional properties

• alignment-adjust ( 7.13.1 ; 346),

• alignment-baseline ( 7.13.2 ; 346),

• baseline-shift ( 7.13.3 ; 351),

• dominant-baseline ( 7.13.5 ; 374),

• id ( 7.28.2 ; 384),

• keep-with-next ( 7.19.4 ; 386),

• keep-with-previous ( 7.19.5 ; 387),

• letter-spacing ( 7.16.2 ; 389),

• line-height ( 7.15.4 ; 390),

• score-spaces ( 7.28.6 ; 412),

• text-altitude ( 7.27.4 ; 421),

• text-decoration ( 7.16.4 ; 422),

• text-depth ( 7.27.5 ; 422),

• text-shadow ( 7.16.5 ; 423),

• text-transform ( 7.16.6 ; 423),

• visibility ( 7.28.8 ; 425),

• word-spacing ( 7.16.8 ; 428),

• wrap-option ( 7.15.13 ; 428).

Shorthands influencing the above properties

• font ( 7.29.13 ; 377),

• page-break-after ( 7.29.16 ; 401),

• page-break-before ( 7.29.17 ; 401),

• vertical-align ( 7.29.22 ; 424).

7.2.4 Dynamic content in static content

It is often necessary to redefine header information more often than once per page sequence.

• Starting a new page sequence starts a new page.

• A page sequence of chapter content may require section headings to change when section breaks do not start a new page.

• "Dictionary heads" are used in a dictionary presentation with many entries per page.

  • The top left of the left-page header indicates the first word found on the page.

  • The top right of the right-page header indicates the last word found on the page.

  • The formatter must be told which of the possibilities is desired for choosing the first or last entry on the page.

    • Is it the first or last entry that begins on the page?

    • Is it the first or last entry where any part of the definition is on the page?

Dynamic content that is a candidate for inclusion in static content is captured in the flow using the marker object.

• The marker's parent's total area is called a "qualifying area" for the marker.

  • The marker is associated with all of the non-normal areas in the qualifying area.

• The "containing page" is the page containing the first of the areas that would have been rendered for the marker if the marker were rendered in place.

  • Marker descendants do not inherit inheritable properties of the marker or its ancestors .

  • Marker descendants do inherit inheritable properties of where the marker is retrieved.

• Two markers with the same parent object must not have the same marker-class-name property.

  • A marker must either be the first child of its parent object, or only have other sibling markers before it.

It is necessary to have canvas information duplicated to be retrieved.

• The marker definition is not rendered on the canvas, only the retrieval.

• If the static content needs to be the same as the canvas content, the content must be duplicated in the flow.

Preference is afforded to the parents of nested markers based on their position in the area tree hierarchy.

• Areas higher in the tree (pre-order traversal) are preferred to the areas lower in the tree.

• Higher preference is given to a page than to the page that precedes it.

Areas in the area tree have associated markers for each marker class.

• The retrieval algorithm notes the first, last, or any areas of a marker on a page.

• A page may validly not contain any first or last area for a given marker class.

Consider Figure 7-3 that shows four pages generated in the area tree.

• The first page has only one first or last area associated with any marker.

  • "A" is the first and last marker whose first area is on the page.

• The second page doesn't have the first or last area associated with any marker.

  • "A" is the only marker with any area on the page.

• The third page has a number of such areas.

  • "A" is the first marker where any of its areas is on the page.

  • "B" is the first marker whose first area is on the page.

  • "B" is the last marker whose last area is on the page.

  • "C" is the last marker whose first area is on the page.

• The fourth page has only one first or last area associated with any marker.

  • "C" is the first and last marker whose last area or any area is on the page.

Figure 7-3. Adding to the area tree the first, last, and other areas for a marker

Only static content may contain retrieve-marker constructs.

• They reference the marker named by the retrieve-class-name property.

  • The marker's content is added to the static content in place of the retrieval construct.

Dynamic content inherits properties ancestral to the referencing retrieve-marker construct.

• Properties are inherited as if the formatting objects of the marker content existed at the retrieval point.

You can scope the search for a marker to be retrieved by using retrieve-boundary property

• looking only on the page,

• looking either on the page or on an earlier page in the same page sequence (default),

• looking either on the page or on any earlier page in the document.

You can ask for the areas of a particular marker based on the marker's position by using retrieve-position property

• first marker where any area within its parent is in the scope,

• first marker whose first area within its parent is in the scope (default),

• last marker whose last area within its parent is in the scope,

• last marker whose first area within its parent is in the scope.

Consider the production of "dictionary heads" where every entry in the dictionary includes a marker child and the header reflects the first and last entry on the page for navigation purposes, as shown in Figure 7-4.

Figure 7-4. Options for retrieving markers

7.2.5 The marker object

Purpose

• This is the replacement formatting object content for a marker retrieved in static content.

• It is associated with all of the areas generated by its parent formatting object.

Content

• ( 6.11.3 ) (#PCDATA %inline; %block; )* ,

• child objects (listed alphabetically ):

  • %block; ( 6.2 ; 69),

  • %inline; ( 6.2 ; 70).

• Content validity is dependent on the context of the corresponding retrieve-marker object that the marker object replaces .

Required property

• marker-class-name ( 7.23.1 ; 393).

Consider in Example 7-3 a single-sided presentation where the header retrieves a section's title. Each section is surrounded by a block that includes a marker (highlighted in the example) that is thereby associated with the contents of the surrounding block. Note how the arrangement of the section title in the marker is different than that used in the body of the page.

7.2.6 The retrieve-marker object

Purpose

• This is an inline-level placeholder replaced with the formatting objects of the indicated marker.

Content

• ( 6.11.4 ) EMPTY .

Required property

• retrieve-class-name ( 7.23.2 ; 409).

Optional properties

• retrieve-boundary ( 7.23.4 ; 409),

• retrieve-position ( 7.23.3 ; 409).

Example 7-3 Defining markers

 Line 01 <page-sequence master-reference="frame">      02   <static-content flow-name="frame-before">      03     <block text-align="end" font-weight="bold"      04            color="silver" font-size="12pt">      05       <retrieve-marker retrieve-class-name="section"/>      06     </block>      07   </static-content>      08   ...      09   <flow flow-name="frame-body">      10     ...      11     <block>      12  <marker marker-class-name="section">Section One - 1.</marker>  13       <block>1. Section One</block>      14       <block space-before="1em">This is a test</block>      15       <block space-before="1em">This is a test</block>      16       ...      17       <block space-before="1em">This is a test</block>      18       <block space-before="1em">This is a test</block>      19     </block>      20       21     <block space-before="2em">      22  <marker marker-class-name="section">Section Two - 2.</marker>  23       <block>2. Section Two</block>      24       <block space-before="1em">This is a test</block>      25       <block space-before="1em">This is a test</block>      26       ...      27       <block space-before="1em">This is a test</block>      28       <block space-before="1em">This is a test</block>      29     </block> 

Properties of note

• retrieve-boundary can be used to limit the search for a marker within the page, to the beginning of the page sequence (default), or to the beginning of the document.

• retrieve-position is illustrated in Figure 7-3.

This is highlighted in Example 7-4 using the earlier example of section title citations in a header.

7.2.7 Planning a simple page sequence specification

Figure 7-5 shows how planning ahead can make page sequence specifying easier.

Example 7-4 Retrieving markers

 Line 01 <page-sequence master-reference="frame">      02   <static-content flow-name="frame-before">      03     <block text-align="end" font-weight="bold"      04            color="silver" font-size="12pt">      05  <retrieve-marker retrieve-class-name="section"/>  06     </block>      07   </static-content>      08   ...      09   <flow flow-name="frame-body">      10     ...      11     <block>      12       <marker marker-class-name="section">Section One - 1.</marker>      13       <block>1. Section One</block>      14       <block space-before="1em">This is a test</block>      15       <block space-before="1em">This is a test</block>      16       ...      17       <block space-before="1em">This is a test</block>      18       <block space-before="1em">This is a test</block>      19     </block>      20       21     <block space-before="2em">      22       <marker marker-class-name="section">Section Two - 2.</marker>      23       <block>2. Section Two</block>      24       <block space-before="1em">This is a test</block>      25       <block space-before="1em">This is a test</block>      26       ...      27       <block space-before="1em">This is a test</block>      28       <block space-before="1em">This is a test</block>      29     </block> 

• Consider planning a book with a table of contents followed by content in separate page sequences each using the same page geometry for before and after regions.

• A single-sided presentation with the page number is at the bottom of all pages.

  • Static content indicates the current and last page numbers.

• Headers are formatted differently for the table of contents and for chapter contents.

  • The document title is shown in the content page sequences but not in the TOC page sequence.

    • The TOC page sequence has a different definition of static content than the content page sequences.

Figure 7-5. Page sequence planning simple example