[Accessibility conventions are described at the bottom of the page]

5. Generic body constructs
[> 6.][< 4.3.6][^^^]
5.0 Often-used formatting constructs
[> 5.1][> 6.][< 5.][^^][^^^]
Many publishing requirements involve the following commonly-used constructs:
[[1] - pairs of aligned block-level layout areas in the inline-progression direction
[[2] - normally flowing a block-level area breaks the block progression direction, stacking the block area after the previous area
[[3] - holds two block-level areas stacked beside each other
 [3] - block areas are aligned on their respective before edges
][2] - coupled members (e.g. side-by-side translated polyglot (multi-language) text)
 [2] - unordered members of a collection (e.g. bulleted lists)
 [2] - ordered members of a collection (e.g. sequenced lists with labels of alpha, roman, number, etc.)
][1] - non-textual information
[[2] - static images or dynamic windows into live applications
 [2] - information external to the XSL-FO instance
[[3] - mandatory for non-XML expressions of the information
 [3] - optional for XML expressions of the information (e.g. SVG)
][2] - information embedded in the XSL-FO instance
[[3] - must be an XML expression of the information (e.g. SVG)
]][1] - unidirectional associations of information
[[2] - from areas of the area tree to a target external resource
 [2] - from areas of the area tree to a target area in the same area tree
 [2] - interactivity engaged by the operator viewing the rendered result can navigate the operator to the target location triggering a traversal of the association
 [2] - unidirectional links have no "back link" information to retrace steps
[[3] - such functionality in browsers and page turner applications is maintained by the application itself, not by the inherent properties of the link
]][1] - elastic and inelastic inline areas and decorations
[[2] - forcing inline items to the opposite boundaries of a line
 [2] - assistance when the eye travels from one side of a page to the opposite side
[[3] - used in entries in tables of content
][2] - patterned sequences of characters joining information on a single line
[[3] - e.g. a dot leader
][2] - drawn rules in the inline-progression direction
[[3] - a non-textual straight-ruled mark
][2] - when the length is specified the construct is inelastic
[[3] - useful standalone to break up the flow of information with visual barriers
][2] - when the length cannot be predetermined, the construct can be elastic
[[3] - grows to the length needed
]]]
An example of a side-by-side bilingual text presentation of an excerpt from the Canadian statute "Employment Equity Act, S.C. 1995, c. 44":
[Figure 5.1: English and French side-by-side tabular presentation
A page of side-by-side English and French text is shown with aligned paragraph starts. The paragraph pairs are rendered in table rows, thus guaranteeing the before alignment of the two members of the pair.
]
Note:
[[1] - the paragraphs are aligned at the before edges
 [1] - the sizes of the respective paragraphs are different
 [1] - no need to calculate the distance needed to align the starts of paragraphs
]
Aligned pairs of block-level layout areas can be used for different purposes
[[1] - side-by-side presentation
[[2] - e.g. simultaneous translation with aligned paragraphs
][1] - traditional list structures
[[2] - e.g. numbered lists, bulleted lists, terminology definitions, etc.
]]
[Figure 5.2: Aligned layout areas
Two separate pages are shown, the one on the left with like-sized label and body blocks for parallel aligned content, and the one on the right as a traditional list content. Each page shows a single list and its constituent components. None of the components are labeled.
]
The same XSL-FO semantic is used for both kinds of layout above.
The samp/leadlink.fo example illustrates leaders, links and graphics:
[Figure 5.3: Example for leaders, links and graphics
A formatted table of contents is shown, with three chapter titles on the left and dotted-line leaders to respective page numbers on the right. An additional line shows the total page count in a similar fashion.
Between the title and subtitle are 5 horizontal lines: the top two are close together, the bottom two are close together, and the middle one is about equidistant between the top two and the bottom two.
Centered after the "Table of Contents" header is a small graphic showing two flags.
]
The text of each line of the table of contents is "hot"
[[1] - the operator interacts with a hot area in order to traverse a link
[[2] - e.g. a mouse click
][1] - the operator is moved to the focus to the target of the association
[[2] - e.g. another page in the same XSL-FO formatted result
 [2] - e.g. a page in the another XSL-FO formatted result
 [2] - e.g. a web browser with a web page address
]]
A graphic image shown below the title
[[1] - in this example, this is an external bit image
]
Various leaders are used on the page
[[1] - near the top there are inelastic rule leaders 100% of the width of the page
 [1] - above the page count there is an inelastic rule leader 60% the width of the page
 [1] - in each entry there is an elastic dot leader that stretches between the start-aligned titles and the end-aligned page numbers
]
The XSL-FO objects covered in this chapter are summarized as follows.
List objects:
[[1] - <[list-block]> ([6.8.2])
[[2] - the collection object of a related set of child member pairs of aligned block-level areas
][1] - <[list-item]> ([6.8.3])
[[2] - a member pair of aligned block-level areas in a collection
][1] - <[list-item-label]> ([6.8.5])
[[2] - the start-side member of a pair of aligned block-level areas
][1] - <[list-item-body]> ([6.8.4])
[[2] - the end-side member of a pair of aligned block-level areas
]]
Graphic objects:
[[1] - <[external-graphic]> ([6.6.5])
[[2] - the inline display of graphical or other externally-supplied information
][1] - <[instream-foreign-object]> ([6.6.6])
[[2] - the inline display of graphical or other instance-supplied information
][1] - [F1.1]<[scaling-value-citation]> ([6.6.15])
[[2] - the inline display of scaling factor applied to the cited instance-supplied object or externally-supplied information
]]
Link object:
[[1] - <[basic-link]> ([6.9.2])
[[2] - the inline display of the start resource of a unidirectional link to a single end point
]]
Leader/rule object:
[[1] - <[leader]> ([6.6.9])
[[2] - the inline elastic or rigid display of a rule or a repeated sequence of characters
]]
5.1 Lists
[> 5.2][< 5.0][^^][^^^]
5.1.1 Aligned pairs of block-level constructs
[> 5.1.2][> 5.2][> 6.][< 5.0][^^][^^^]
Standalone blocks cannot be adjacent to each other in the inline-progression direction
[[1] - a block-level construct typically restarts in the block-progression direction as a following sibling
]
Pairs of adjacent blocks are useful to associate the information in one of the pair to the information in the other of the pair
[[1] - side-by-side polyglot (multi-language) text
[[2] - e.g. aligned translation paragraphs
][1] - terms and their definitions
 [1] - generic list item formatting
[[2] - the item enumerator and the item content
]]
The name of the construct shouldn't prejudice how the construct is used
[[1] - don't consider that only lists in your XML information can use this construct for layout
 [1] - regard the construct as a layout facility for two block-level constructs in the inline-progression direction of the parent block
 [1] - a two-column table construct may suffice or offer other layout features you need
]
Specialized properties are available for behaviors characteristic of list processing
[[1] - provisional property values can be used to make the calculated property values of the two blocks relative to each other instead of independent of each other
 [1] - no obligation to use the specialized properties
]
The content of the blocks does not impact on the start/end edges of the blocks
[[1] - the start and end edges of each block are set absolutely or relative to each other, but not relative to the length of the content
 [1] - when using provisional values and functions, the edges are fixed to the same values for all members of the entire list
[[2] - planning ahead is necessary to ensure any undesired wrapping within edges is avoided
][1] - when specifying margins on a per list item basis, the edges can be explicitly specified differently than other list items
[[2] - cannot measure the content of a label or body in order to set the margins relative to the content
]]
5.1.2 List constructs
[> 5.1.3][> 5.2][> 6.][< 5.1.1][^][^^][^^^]
A list is a block-level object:
[[1] - it contains only list-items (pairs)
[[2] - it requires a nested list to itself be a list item unless it is already in a list item
][1] - each item has the two components of the pair:
[[2] - the list item label (the member of the pair on the start side)
 [2] - the list item body (the member of the pair on the end side)
]]
[Figure 5.4: The blocks of information that comprise a list
The constructs of a list are illustrated using nested boxes approximately placed as if formatted on a page as a vertical list.
Two separate pages are shown, the one on the left with like-sized label and body blocks for parallel aligned content, and the one on the right as a traditional list content. Each page shows a single list and its constituent set of constructs.
Each entire set is labeled "list-block."
The first member in each is a box labeled "list-item," implying that each of the members are also list-item constructs.
Two boxes are drawn and labeled and aligned at the top within the list-item: the list-item-label to the left and the list-item-body to the right. The list-item-label is drawn differently in each list-item of the right-hand illustration and is small in relation to the multi-line list-item-body corresponding to each list-item.
]
Block alignment can involve more than two blocks:
[[1] - the body of a list item can itself contain a list with two aligned blocks
 [1] - the initial value of relative alignment is the before edge for all blocks
]
[Figure 5.5: Synchronizing more than two blocks
The constructs of a list nested inside a list is illustrated showing the outermost list block's first list item's body containing a list block with its own list item.
The before edges of the outer list item label and inner list item label and list item block are all aligned.
]
One could consider using a table for more than two blocks
[[1] - table properties allow proportional sizes of the block widths
]
Vertical alignment of list item label defaults to a common before edge
[[1] - ensures the before edge of the first block on each side is aligned on the page
 [1] - [relative-align]= can be set to common text baseline of first lines
[[2] - when different font sizes are used without aligning to the text baseline, the smaller of the two font sizes will appear to be superscripted
]]
Horizontal indentation of the list item components is the responsibility of the stylesheet writer:
[[1] - the item label's [start-indent]= is specified explicitly (or inherited)
 [1] - the item body's [end-indent]= is specified explicitly (or inherited)
 [1] - the item label's [end-indent]= and item body's [start-indent]= can be independently set and may be different for each item
[[2] - will result in inconsistent presentation of the labels in parent areas of different widths
[[3] - e.g. in differing media (US-letter and A4 page sizes have different widths)
][2] - without proper planning can inadvertently result in display problems
[[3] - overlapping label content on top of body content (an error)
 [3] - undesired wrapping of the label content
]][1] - the item label's [end-indent]= and item body's [start-indent]= can be set relative to the [start-indent]= of the item label and is the same for each item
[[2] - guarantees consistent label presentation in parent areas of different widths
[[3] - e.g. changing the paper width will not change the presentation of the labels
][2] - the stylesheet can ask the processor to dynamically set these values on a per list item basis
 [2] - protects the content of the two areas from sharing the same place on the rendered output
]]
Not obliged to use [body-start]() or [label-end]():
[[1] - can specify the distances from the parent edges explicitly for each of the label and body
]
[Figure 5.6: Simple adjacent blocks in a list
The various list properties are drawn with arrows pointing the reader to an indication of where the property applies. These are covered later in the text.
No use of the relative property calculations [body-start]() or [label-end]() is shown.
]
Risk of overlap is borne by the stylesheet writer
[[1] - a common error when starting a stylesheet is to forget to set any margins and to witness both blocks of content superimposed within the parent area
 [1] - another common error after writing a stylesheet is to change the page width and not think to change the list item member indents
[[2] - e.g. widening the page dimensions from A4 to US-letter
 [2] - the blocks could overlap in the middle when the distances from the edges are used
 [2] - XSL-FO 1.0 states the overlap is an error, so this cannot be relied upon as an effect
]]
Using [body-start]() and [label-end]() will prevent edges from overlapping and keep label area formatting consistent:
[Figure 5.7: Basic edges on relative calculations
The various list properties are drawn with arrows pointing the reader to an indication of where the property applies. These are covered later in the text.
Use of the relative property calculations [body-start]() or [label-end]() is shown.
]
Relative indentation of the list item components:
[[1] - processor notes [provisional-distance-between-starts]= and [provisional-label-separation]= values for built-in functions
[[2] - "provisional" indicates the value is used as part of an arithmetic calculation
 [2] - values are properties of the list and cannot be set on an individual item
 [2] - specifying a separation ensures to overlap of the label and body
][1] - two built-in functions reflect the above two values in the context of the item label's [start-indent]= and can (should) be used to protect the adjacent area boundaries from each other and ensure consistent label area formatting for different parent widths:
[[2] - label-end()
[[3] - the distance from the end of the label to the end of the line accommodating the indent of the label
 [3] - used as the value for the [end-indent]= property of the item label
][2] - body-start()
[[3] - the distance from the start of the line to the start of the body accommodating the indent of the item label
 [3] - used as the [start-indent]= property of the item body
]]]
5.1.3 Nested list constructs
[> 5.1.4][> 5.2][> 6.][< 5.1.2][^][^^][^^^]
The nesting of lists may require the use of hidden list-item members
[[1] - an XSL-FO list can only contain list items (see [Figure 5.4])
 [1] - a nested list in user's XML vocabulary is usually one of either:
[[2] - a block within an existing list item
[[3] - e.g. list/listitem/list
 [3] - the block-level <[list-block]> formatting object can flow with other blocks inside a <[list-item-body]>
][2] - its own list item
[[3] - e.g. list/list
 [3] - a list-block can only contain list-item children
[[4] - thus requiring a hidden list-item within which the list block is placed in the body
][3] - the hidden list-item children must have blocks for labels
[[4] - the label blocks can be empty to hide the fact they are list items
]]]]
Determining the need depends on:
[[1] - for dependence of the indentation of the nested list
[[2] - is its indentation fixed?
[[3] - use the body of a hidden list item with a fixed indentation for the body
][2] - is its indentation relative to the indentation of the label of the list item in which it is flowed?
[[3] - could use the calculated body start indentation of the preceding list item
 [3] - could flow the nested list at the end of the preceding list item's body
]][1] - the nature of the source list
[[2] - (typical) is the nested list inside one of the list items? (e.g. HTML, DocBook)
[[3] -
<list>
 <item>
  <p>...</p>
  <list>nested list</list>
 </item>
 <item>...
][2] - (atypical) is the nested list a sibling of other list items?
[[3] -
<list>
 <item>
  <p>...</p>
 </item>
 <list>nested list</list>
 <item>...
]]]
The use of a ghost list item prevents violating the content model rules for the containing list
[Figure 5.8: Two methods of nesting a list
Two alternative organizations of a nested list are shown. Each has a two-item list nested after the first of a two-item list.
The one on the left shows the nested list within and at the end of the list item body of the first list item. The nested list is bounded by the bounds of the outer list item body.
The one on the right shows a ghost second list item after the first list item. The label of this list item is empty. The entire nested list is inside the list body of the ghost item. The bounds of the ghost list item body are independent of the bounds of the list item bodies of the other outer list items.
]
Cannot use just a <[block]> or <[list-block]>
[[1] - a <[list-block]> can only contain <[list-item]> children
 [1] - the ghost list item contains the nested list in the body of the item
[[2] - requires an empty block in the label to not be visible on the page
]]
5.1.4 <list-block> Object
[> 5.1.5][> 5.2][> 6.][< 5.1.3][^][^^][^^^]
Purpose:
[[1] - the parent object of a related set of pairs of synchronized block-level areas laid out in the inline-progression direction
]
Content:
[[1] - ([6.8.2]) ([​list-item]+)
 [1] - Child object:
[[2] - <[list-item]>([6.8.3];[Section 5.1.5 <list-item> Object])
]]
[[1] - may begin with any number of <[marker]> children
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Margin Properties-Block]([7.11];[Section D.1.7 Common Margin Properties-Block])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[break-after=]([7.20.1];[Section D.3.3 Property summary])
[break-before=]([7.20.2];[Section D.3.3 Property summary])
[clear=]([7.19.1];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[intrusion-displace=]([7.19.3];[Section D.3.3 Property summary])
[keep-together=]([7.20.3];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[provisional-distance-between-starts=]([7.30.12];[Section D.3.3 Property summary])
[provisional-label-separation=]([7.30.11];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[page-break-inside=]([7.31.18];[Section D.3.3 Property summary])
Properties of interest:
[[1] - [provisional-distance-between-starts]= specifies the desired distance between the start of the list item label and the start of the list item body
 [1] - [provisional-label-separation]= specifies the desired distance between the end of the list item label and the start of the list item body
]
[Example 5-1: The list block A <[list-block]> construct from the earlier [Figure 2.10]:
01   <block space-before="6pt" font-size="14pt">
02   This page's material as an instructor-led handout:</block>
03   <list-block provisional-distance-between-starts=".43in"
04   provisional-label-separation=".1in"
05   space-before="6pt">
06   <list-item relative-align="baseline">
07   <list-item-label text-align="end" end-indent="label-end()">
08   <block>-</block>
09   </list-item-label>
10   <list-item-body start-indent="body-start()">
11   <block font-size="14pt">excerpts of formatting objects created
12   through the use of an XSLT stylesheet</block>
13   </list-item-body>
14   </list-item>
15   </list-block>
]
Separation between the label and body is specified
[[1] - the label is .33 inches wide and .1 inches away from the body
]
5.1.5 <list-item> Object
[> 5.1.6][> 5.2][> 6.][< 5.1.4][^][^^][^^^]
Purpose:
[[1] - the parent of a single pair of synchronized block-level areas laid out in the inline-progression direction
[[2] - indents are relative to containing <[list-block]> object
]]
Content:
[[1] - ([6.8.3]) ([​list-item-label],[​list-item-body])
 [1] - Child objects (alphabetical):
[[2] - <[list-item-body]>([6.8.4];[Section 5.1.7 <list-item-body> Object])
 [2] - <[list-item-label]>([6.8.5];[Section 5.1.6 <list-item-label> Object])
][1] - Referring object:
[[2] - <[list-block]>([6.8.2];[Section 5.1.4 <list-block> Object])
]]
[[1] - may begin with any number of <[marker]> children
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Margin Properties-Block]([7.11];[Section D.1.7 Common Margin Properties-Block])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[break-after=]([7.20.1];[Section D.3.3 Property summary])
[break-before=]([7.20.2];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[intrusion-displace=]([7.19.3];[Section D.3.3 Property summary])
[keep-together=]([7.20.3];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[relative-align=]([7.14.6];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[page-break-inside=]([7.31.18];[Section D.3.3 Property summary])
Property of interest:
[[1] - [relative-align]= determines the alignment of the list item with either the before edge of the list body (default) or the baseline of the first line area generated by the list body
[[2] - the value "baseline" is typically used when both sides are using text
 [2] - the value "before" is typically used when one or both sides are graphics
]]
[Example 5-2: The list item A <[list-item]> construct from the earlier [Figure 2.10]:
01   <block space-before="6pt" font-size="14pt">
02   This page's material as an instructor-led handout:</block>
03   <list-block provisional-distance-between-starts=".43in"
04   provisional-label-separation=".1in"
05   space-before="6pt">
06   <list-item relative-align="baseline">
07   <list-item-label text-align="end" end-indent="label-end()">
08   <block>-</block>
09   </list-item-label>
10   <list-item-body start-indent="body-start()">
11   <block font-size="14pt">excerpts of formatting objects created
12   through the use of an XSLT stylesheet</block>
13   </list-item-body>
14   </list-item>
15   </list-block>
]
5.1.6 <list-item-label> Object
[> 5.1.7][> 5.2][> 6.][< 5.1.5][^][^^][^^^]
Purpose:
[[1] - the start-side member of a pair of synchronized block-level areas laid out in the inline-progression direction
]
Content:
[[1] - ([6.8.5]) ([​%block;])+
 [1] - Child object:
[[2] - [%block;]([6.2];[Section 3.4.2 Block-level objects])
][1] - Referring object:
[[2] - <[list-item]>([6.8.3];[Section 5.1.5 <list-item> Object])
]]
[[1] - may begin with any number of <[marker]> children
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
]
Other optional properties:
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[keep-together=]([7.20.3];[Section D.3.3 Property summary])
Shorthand influencing the above properties:
[page-break-inside=]([7.31.18];[Section D.3.3 Property summary])
Property of interest:
[[1] - [end-indent]= can utilize the label-end() function
]
[Example 5-3: The list item's label A <[list-item-label]> construct from the earlier [Figure 2.10]:
01   <block space-before="6pt" font-size="14pt">
02   This page's material as an instructor-led handout:</block>
03   <list-block provisional-distance-between-starts=".43in"
04   provisional-label-separation=".1in"
05   space-before="6pt">
06   <list-item relative-align="baseline">
07   <list-item-label text-align="end" end-indent="label-end()">
08   <block>-</block>
09   </list-item-label>
10   <list-item-body start-indent="body-start()">
11   <block font-size="14pt">excerpts of formatting objects created
12   through the use of an XSLT stylesheet</block>
13   </list-item-body>
14   </list-item>
15   </list-block>
]
Of note:
[[1] - the end alignment is specified on the label to move the content of the label as close as possible to the body
 [1] - this supports the appearance of variable length labels (i.e. Roman characters) with a common distance between the label and the body
]
5.1.7 <list-item-body> Object
[> 5.1.8][> 5.2][> 6.][< 5.1.6][^][^^][^^^]
Purpose:
[[1] - the end-side member of a pair of synchronized block-level areas laid out in the inline-progression direction
]
Content:
[[1] - ([6.8.4]) ([​%block;])+
 [1] - Child object:
[[2] - [%block;]([6.2];[Section 3.4.2 Block-level objects])
][1] - Referring object:
[[2] - <[list-item]>([6.8.3];[Section 5.1.5 <list-item> Object])
]]
[[1] - may begin with any number of <[marker]> children
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
]
Other optional properties:
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[keep-together=]([7.20.3];[Section D.3.3 Property summary])
Shorthand influencing the above properties:
[page-break-inside=]([7.31.18];[Section D.3.3 Property summary])
Property of interest:
[[1] - [start-indent]= can utilize the body-start() function
]
[Example 5-4: The list item's body A <[list-item-body]> construct from the earlier [Figure 2.10]:
01   <block space-before="6pt" font-size="14pt">
02   This page's material as an instructor-led handout:</block>
03   <list-block provisional-distance-between-starts=".43in"
04   provisional-label-separation=".1in"
05   space-before="6pt">
06   <list-item relative-align="baseline">
07   <list-item-label text-align="end" end-indent="label-end()">
08   <block>-</block>
09   </list-item-label>
10   <list-item-body start-indent="body-start()">
11   <block font-size="14pt">excerpts of formatting objects created
12   through the use of an XSLT stylesheet</block>
13   </list-item-body>
14   </list-item>
15   </list-block>
]
5.1.8 When is a list not a list?
[> 5.2][> 6.][< 5.1.7][^][^^][^^^]
Some formatting requirements for lists cannot be satisfied with the <[list-block]> construct when the margins of the list items need to reflect the contents of the list
[[1] - <[list-block]> forces the stylesheet writer to specify the start and end edges of the labels and bodies of the items, which cannot be based on the length of the content
 [1] - one is not obliged to use <[list-block]> to format a list-like source construct
]
Consider three alternative approaches to satisfy the need to format three list items where the item labels are distinctly different lengths, none of which is known by the stylesheet writer
[Figure 5.9: Three alternatives to using a list construct for a list
Three page fragments are shown with thick-lined boxes indicating table constructs, dotted lines indicating the table cell boundaries, and thin-lined boxes indicating the blocks of the item labels and bodies.
The left-most page fragment shows three list items in a single table with the three labels in a single column whose width is the width of the longest label.
The center page fragment shows three list items in three separate tables of one row each where each label's column width is the width of that item's label.
The right-most page fragment shows three pairs of blocks, where the label block is as wide as the label and shrinks the width of the body accordingly such that the body fills the rest of the page width. The label block accomplishes this pushing through the use of a side-float trait.
]
Basing the indentation of all item bodies on the longest length of all item labels
[[1] - can use one table for entire list contents (e.g. left page image)
[[2] - hidden borders and auto-calculated column widths with all rows reflecting a single set of column widths
 [2] - use one row for each list item with auto width calculation of the first column determining longest label
[[3] - may not work well if the label has spaces that will promote cell balancing
]]]
Basing the indentation of each item body on the length of corresponding item labels
[[1] - can use a one-row table for each list item (e.g. center page image)
[[2] - hidden borders and auto-calculated column widths for each individual row in separate table
 [2] - use as many tables as there are list items
][1] - can use a side-float aligned with the block (e.g. right page image)
[[2] - each body block is prefaced with a side float block with the label whose size squeezes the body block width
]]
5.2 Graphics and foreign objects
[> 5.3][< 5.1.8][^^][^^^]
5.2.1 Non-textual information
[> 5.2.2][> 5.3][> 6.][< 5.1.8][^^][^^^]
Graphic and other non-textual constructs can come from two possible sources
[[1] - external files
[[2] - <[external-graphic]/>
 [2] - a URI specifies how to obtain the external resource
][1] - embedded use of non-XSL-FO namespace constructs
[[2] - <[instream-foreign-object]>
 [2] - the use of namespaces ensures no confusion with XSL-FO objects
 [2] - e.g. Scalable Vector Graphics (SVG), Math Markup Language (MathML), etc.
 [2] - promotes the generation of images from the stylesheets that generate the XSL-FO
[[3] - e.g. charting numbers from the XML instance into SVG constructs
]]]
XSL-FO processor need not recognize the formats, only pass on the content from whatever source to rendering agent for imaging
[[1] - the formatter is only responsible for measuring and allocating the required area on the page as indicated by the properties
 [1] - rendering agent must recognize the file type by either name or content
[[2] - no notation information communicated through the stylesheet from the DTD
]]
Content need not be a static graphic image
[[1] - could be a window into an application user interface
[[2] - e.g. spreadsheet
]]
Scaling is necessary when the image intrinsic size is larger than the page and you need it to fit
[[1] - [content-width]="scale-to-fit" [width]="100%"
 [1] - could otherwise choose to base scaling on the height
]
When smaller images need to stay small but larger images need to scale
[[1] - rely on the engine's on-the-fly choice of the smaller of two width sizes:
scaling="uniform"
width="100%" content-width="scale-to-fit"
content-height="100%"
 [1] - or rely on the engine's on-the-fly choice of the smaller of two height sizes:
scaling="uniform"
height="100%" content-height="scale-to-fit"
content-width="100%" 
 [1] - the [scaling]="uniform" ensures the resulting aspect ratio is not distorted
 [1] - need to choose one of the two dimensions as a governing dimension for the calculations, for example, by choosing width:
[[2] - the [content-width]="scale-to-fit" will scale the image to the specified viewport [width]="100%" of the available width
 [2] - the [content-height]="100%" ensures that the image width is not enlarged to 100% of the viewport when the width is smaller
][1] - the similar interpretation would work in the other dimensions when choosing height as the governing dimension
]
The [src]= property has specific syntactic requirements
[[1] - safest to use: url("uri-value-here")
[[2] - the author of the XML document may be creating the URI being used in the resulting syntax
 [2] - the URI character set includes the single quote that would bring about an improperly formed attribute value
][1] - could use no quote delimiters, but not if content has a single quote
 [1] - could use single quote delimiters, but not if content has a single quote
 [1] - ensure XML syntax for attribute use of quotes is acceptable:
[[2] - e.g. src='url("uri-value-here")'
 [2] - e.g. src="url(&quot;uri-value-here&quot;)"
][1] - this is not a function call but a syntactic convention
[[2] - without it the URI syntax could ambiguously be interpreted as expression syntax
 [2] - without it any embedded single quotes (which are allowed in URI syntax and could be in the source XML without the stylesheet writer knowing) could confuse the interpretation of the literal string
]]
5.2.2 <external-graphic> Object
[> 5.2.3][> 5.3][> 6.][< 5.2.1][^][^^][^^^]
Purpose:
[[1] - the inline-level display of graphical or other externally-supplied information
[[2] - displayed matter does not reside as part of XSL-FO instance content
[[3] - needs reference to an addressed external resource
][2] - can be placed in a <[block]> object for block-level display
]]
Content:
[[1] - ([6.6.5]) EMPTY
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other required property:
[src=]([7.30.16];[Section D.3.3 Property summary])
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[F1.1][allowed-height-scale=]([7.15.1];[Section D.3.3 Property summary])
[F1.1][allowed-width-scale=]([7.15.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[block-progression-dimension=]([7.15.3];[Section D.3.3 Property summary])
[clip=]([7.21.1];[Section D.3.3 Property summary])
[content-height=]([7.15.4];[Section D.3.3 Property summary])
[content-type=]([7.30.7];[Section D.3.3 Property summary])
[content-width=]([7.15.5];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[height=]([7.15.6];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[inline-progression-dimension=]([7.15.7];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[scaling=]([7.15.12];[Section D.3.3 Property summary])
[scaling-method=]([7.15.13];[Section D.3.3 Property summary])
[text-align=]([7.16.9];[Section D.3.3 Property summary])
[width=]([7.15.14];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
Properties of interest:
[[1] - [text-align]= and [display-align]= are used to align the scaled image's reference area within the viewport area
[[2] - ancestral specifications will align the viewport area within its parent area
 [2] - [width]= and [height]= specify the viewport (size of the graphic window), while [content-width]=, [content-height]= and [scaling]= specify the size of the image, using [overflow]= to hide the image outside the viewport
][1] - [alignment-baseline]= is used to move the image after-edge off the text baseline
]
[Example 5-5: An example of referencing an external resource An excerpt from the [samp/leadlink.fo sample] ([Figure 5.3]):
01  <block font-size="24pt" space-after="16pt" space-before="1cm" 
02   text-align="center">
03   Table of Contents
04   <block/>
05   <external-graphic src="url(&quot;smflags.bmp&quot;)"/>
06   </block>
]
Note the following regarding the above structure
[[1] - by default, white-space is collapsed so that the words "Table of Contents" are flowed on the page as if separated by only one space each
 [1] - the use of the empty block to introduce a line of zero size thus breaking the title and the graphic onto separate lines
 [1] - the use of the protected quoted syntax for the URI of the graphic image
 [1] - the centering of all inline constructs on all lines of the outside block using [text-align]=
]
5.2.3 <instream-foreign-object> Object
[> 5.2.4][> 5.3][> 6.][< 5.2.2][^][^^][^^^]
Purpose:
[[1] - the inline display of graphical or other instance-supplied information
[[2] - displayed matter resides as part of the XSL-FO instance content
[[3] - descendent content of object using a non-XSL-FO namespace
][2] - object can be placed in a <[block]> object for block-level display
]]
Content([6.6.6]):
[[1] - a single child element from a non-XSL-FO namespace
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[F1.1][allowed-height-scale=]([7.15.1];[Section D.3.3 Property summary])
[F1.1][allowed-width-scale=]([7.15.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[block-progression-dimension=]([7.15.3];[Section D.3.3 Property summary])
[clip=]([7.21.1];[Section D.3.3 Property summary])
[content-height=]([7.15.4];[Section D.3.3 Property summary])
[content-type=]([7.30.7];[Section D.3.3 Property summary])
[content-width=]([7.15.5];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[height=]([7.15.6];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[inline-progression-dimension=]([7.15.7];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[scaling=]([7.15.12];[Section D.3.3 Property summary])
[scaling-method=]([7.15.13];[Section D.3.3 Property summary])
[text-align=]([7.16.9];[Section D.3.3 Property summary])
[width=]([7.15.14];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
Properties of interest:
[[1] - [text-align]= and [display-align]= are used to align the scaled image's reference area within the viewport area
[[2] - ancestral specifications will align the viewport area within its parent area
 [2] - [width]= and [height]= specify the viewport (size of the graphic window), while [content-width]=, [content-height]= and [scaling]= specify the size of the image, using [overflow]= to hide the image outside the viewport
][1] - [alignment-baseline]= is used to move the image after-edge off the text baseline
]
[Example 5-6: Example embedding of SVG in XSL-FO An example of embedding an alternate namespace (in this case, Scalable Vector Graphics (SVG)) in XSL-FO instances:
01  <block text-align="center">
02   <block>
03   <instream-foreign-object>
04   <svg:svg xmlns:svg="http://www.w3.org/2000/svg"
05   width="170" height="145">
06   <svg:g style="stroke:black; fill:black">
07   <svg:polygon points=" 5, 50, 5, 81, 12, 64"/>
08   <svg:polygon points=" 5, 45, 41,116, 41, 73"/>
09   <svg:polygon points=" 44, 76, 44,119, 61,115"/>
10   <svg:polygon points=" 46, 73, 75,140,105, 73"/>
11   <svg:polygon points="107, 76,106,119, 89,115"/>
12   <svg:polygon points="144, 45,109,116,109, 73"/>
13   <svg:polygon points="145, 41,167, 4,109, 71"/>
14   <svg:polygon points=" 66, 72, 75, 63, 84, 72"/>
15   </svg:g>
16   </svg:svg>
17   </instream-foreign-object>
18   </block>
19   <block font-size="20pt" font-weight="bold">Crane Logo</block>
20   </block>
]
The rendering of the embedded image
[Figure 5.10: An embedded SVG image
A screen shot of Adobe Acrobat shows the Crane logo above a caption reading "Crane logo".
]
5.2.4 Exposing the image size scaling factor
[> 5.2.5][> 5.3][> 6.][< 5.2.3][^][^^][^^^]
All images have an intrinsic size
[[1] - that size built in to the object's specification
 [1] - for an external image it is the image dimensions
[[2] - each external format has a method of specifying the "default" dimension
][1] - for an inline image it is the image content width
[[2] - e.g. for SVG the size is defined by the grid specified in the height= and width= properties of the document element
]]
[F1.1]<[scaling-value-citation]> exposes as an inline character string the scaling factor used by the formatter for the rendering of an image
[[1] - the integer number of the scaling factor percentage is expressed as a set of digits (without the percent sign)
 [1] - when rendered full size without scaling the value is "100" (without quotes)
[[2] - a shrunken image returns a value less than 100
 [2] - a stretched image returns a value greater than 100
][1] - [ref-id]= points to the image
[[2] - the image needs to have an [id]= property
][1] - [scale-option]= indicates width (default) or height
 [1] - [intrinsic-scale-value]= indicates the intrinsic size of the image specification compared to what is considered the true image size
[[2] - stating intrinsic-scale-value="25%" indicates the intrinsic size found in the object expression is only one quarter of what is considered the image's actual size
][1] - no arithmetic can be performed with the resulting number the formatting object
[[2] - it is just a sequence of characters to be displayed
]]
5.2.5 <scaling-value-citation> Object
[> 5.3][> 6.][< 5.2.4][^][^^][^^^]
Purpose:
[[1] - expose the scaling factor applied to a graphic
]
Content:
[[1] - [F1.1]([6.6.15]) EMPTY
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Font Properties]([7.9];[Section D.1.5 Common Font Properties])
 [1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other required property:
[ref-id=]([7.30.13];[Section D.3.3 Property summary])
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[country=]([7.10.1];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[format=]([7.26.1];[Section D.3.3 Property summary])
[grouping-separator=]([7.26.2];[Section D.3.3 Property summary])
[grouping-size=]([7.26.3];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[F1.1][intrinsic-scale-value=]([7.30.9];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[language=]([7.10.2];[Section D.3.3 Property summary])
[letter-spacing=]([7.17.2];[Section D.3.3 Property summary])
[letter-value=]([7.26.4];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[F1.1][scale-option=]([7.30.14];[Section D.3.3 Property summary])
[score-spaces=]([7.30.15];[Section D.3.3 Property summary])
[text-altitude=]([7.29.4];[Section D.3.3 Property summary])
[text-decoration=]([7.17.4];[Section D.3.3 Property summary])
[text-depth=]([7.29.5];[Section D.3.3 Property summary])
[text-shadow=]([7.17.5];[Section D.3.3 Property summary])
[text-transform=]([7.17.6];[Section D.3.3 Property summary])
[visibility=]([7.30.17];[Section D.3.3 Property summary])
[word-spacing=]([7.17.8];[Section D.3.3 Property summary])
[wrap-option=]([7.16.13];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
[F1.1][xml:lang=]([7.31.24];[Section D.3.3 Property summary])
Properties of interest:
[[1] - [ref-id]= points to the image being reported
 [1] - [scale-option]= indicates width or height
 [1] - [intrinsic-scale-value]= indicates the intrinsic size ratio of the images full size
 [1] - [format]= governs how the page number is represented as a sequence of characters
[[2] - numbers, roman numerals, etc.
 [2] - formally defined by reference to XSLT(see [Format tokens from XSLT 1.0 subset - Section D.2.3 Format tokens from XSLT 1.0 subset])
]]
5.3 Links
[> 5.4][< 5.2.5][^^][^^^]
5.3.1 Link requirements
[> 5.3.2][> 5.4][> 6.][< 5.2.5][^^][^^^]
Unidirectional hyperlinks from clickable content to a target location
[[1] - <[basic-link]>
[[2] - content is the clickable content used by the document reader to traverse to the target of the link
[[3] - requires support by the user agent
 [3] - no need to be supported for a print-only medium
 [3] - any content can be wrapped up in a link construct
][2] - a strict interpretation of the XSL-FO recommendation enforces only the construct's inline area to be "hot" and not the areas generated by descendants of the formatting object
][1] - location can be another point within the document
[[2] - use [internal-destination]= property
 [2] - the user agent software reading the document would navigate the reader to the target page
][1] - location can be a point outside the document
[[2] - use [external-destination]= property
 [2] - the operating system running the user agent software would probably invoke the application associated with the file being pointed to
[[3] - e.g. a web browser for an HTML page
]]]
The object is an inline construct
[[1] - must be placed in a block to be a block-level construct
 [1] - may contain either block-level or inline-level constructs
]
The construct is unidirectional
[[1] - there is no back-link property associated with the link itself
 [1] - the ability for a user agent to "go back" to where the link originated is a function of the user agent based on a history of the user's locations
[[2] - the user agent is not traversing a property of the link itself that indicates where the link was made from
]]
5.3.2 <basic-link> Object
[> 5.4][> 6.][< 5.3.1][^][^^][^^^]
Purpose:
[[1] - the inline display of the start resource of a unidirectional link to a single end point
]
Content:
[[1] - ([6.9.2]) (#PCDATA|[​%inline;]|[​%block;])*
 [1] - Child objects (alphabetical):
[[2] - [%block;]([6.2];[Section 3.4.2 Block-level objects])
 [2] - [%inline;]([6.2];[Section 3.4.3 Inline-level objects])
]]
[[1] - may begin with any number of <[marker]> children
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[destination-placement-offset=]([7.23.5];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[external-destination=]([7.23.6];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[indicate-destination=]([7.23.7];[Section D.3.3 Property summary])
[internal-destination=]([7.23.8];[Section D.3.3 Property summary])
[keep-together=]([7.20.3];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[show-destination=]([7.23.9];[Section D.3.3 Property summary])
[target-presentation-context=]([7.23.12];[Section D.3.3 Property summary])
[target-processing-context=]([7.23.13];[Section D.3.3 Property summary])
[target-stylesheet=]([7.23.14];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[page-break-inside=]([7.31.18];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
[Example 5-7: Link constructs in example An excerpt from the [samp/leadlink.fo sample] ([Figure 5.3]):
01  <block text-align-last="justify" 
02   end-indent="1cm" start-indent="1cm">
03   <basic-link internal-destination="N66">Third Title</basic-link>
04   <leader leader-pattern="dots"/>
05   <basic-link internal-destination="N66">
06   <page-number-citation ref-id="N66"/>
07   </basic-link>
08  </block>
09  ...
10  <block space-before="10pt" text-align-last="justify"
11   end-indent="1cm" start-indent="1cm">
12   <basic-link internal-destination="N1">Page count</basic-link>
13   <leader leader-pattern="dots"/>
14   <basic-link internal-destination="N1">
15   <page-number-citation ref-id="N1"/>
16   </basic-link>
17  </block>
18  ...
19  <page-sequence master-reference="bookpage">
20   <title>The Third Chapter Title</title>
21   <flow flow-name="bookpage-body">
22   <block id="N66" font-size="16pt * 1.5">Third Title</block>
23   <block space-before="16pt">Third entry is very short.</block>
24   <block id="N1"/>
25   </flow>
26  </page-sequence>
]
5.4 Leaders
[> 6.][< 5.3.2][^^][^^^]
5.4.1 Elastic and inelastic inline areas
[> 5.4.2][> 6.][< 5.3.2][^^][^^^]
A leader gives the stylesheet writer a number of basic functions:
[[1] - fixed-length horizontal space, rules or patterns typically used as a separator
[[2] - e.g. a gap between words of precisely .5cm not using spaces
 [2] - e.g. a rule of a particular length used in a form presentation
][1] - elastic leader rules or patterns in tables of content used to aid the eye movement
 [1] - elastic inline gaps used to push away adjacent areas
]
An inline construct that renders a leader along the text baseline of the line
[[1] - <[leader]> - elastic
[[2] - all elastic leaders on a justified line are expanded before any space character or inter-character space on the line is expanded
 [2] - expansion grows evenly across all leaders on the line until the line is full
 [2] - no justification expansion is done on any space characters or inter-character spacing
][1] - <[leader] leader-length="length-value"> - inelastic measured amount
[[2] - a fixed length leader is useful for spacing items on a line
][1] - <[leader] leader-length.optimum=".5em">
[[2] - a "half-font-size" starting size is useful when justifying crowded lines so as to not occupy too much space to begin with
 [2] - when using only .optimum=, the .maximum= is 100% and the .minimum= is 0pt
 [2] - when using leader-length= the optimum, min and max are the same
 [2] - the default .optimum= size is 12pt which might be too big for the line
][1] - must be put into a stand-alone block to act as a block construct
[[2] - note the default line height of the block is the font size, not the line height of the highest construct
 [2] - without specifying a small line height on the block, adjacent blocked lines will not appear close together
]]
When used as a leader from one margin to the other margin, must use [text-align-last]= property on the containing block
[[1] - using [text-align]= is insufficient for the value "justify" because the line of a single-line block is considered the last line of the block
 [1] - the leader grows between the information at the start of the line and the information at the end of the line
[[2] - e.g. a dot leader used in table of contents entries
 [2] - e.g. an empty leader pushing two pieces of information to each end of the same line
]]
The [samp/leadlink.fo sample] ([Figure 5.3]) illustrates basic needs
[[1] - block-level leaders are used as separators and decoration
[[2] - special block-level considerations for tightly-spaced leaders
 [2] - block-level leaders need not be full block width
][1] - title entries are short
[[2] - leaders expand between end of title and start of page number
]]
The samp/leaders.fo example illustrates complex table of contents formatting requirements:
[[1] - the author of the XML being formatted is responsible for the length of titles
 [1] - the stylesheet is collecting and presenting the titles in a table of contents
 [1] - short titles are easily accommodated through simple margin specifications
 [1] - if the user could possibly create long titles, the stylesheet writer should be prepared to accommodate wrapping conditions to avoid confusion when reading the table
[[2] - wrapping at the start of the line could confuse the count of entries in the table of contents
[[3] - the wrapping point should be indented on the start side
][2] - wrapping at the end of the line could confuse the presentation of page numbers
[[3] - the wrapping point should be indented on the end side
]][1] - a block's first and last lines can be hanging in respective outdents to give the desired unambiguous presentation at the starts and ends of the lines
]
[Figure 5.11: Example for long titles with leaders
A table of contents with four entries is shown, the third of which has a title that is very short resulting in a single line being formatted. The other entries have lengthy titles that require four lines to be formatted to contain the content. The lengthy titles hang out on the left on the first line and hang out on the right on the fourth line, the outer bounds lining up with the outer bounds of the single line third entry.
]
Note that the lines of the block are shown only to illustrate the dimension of the block construct itself; this was done simply by turning on the border-style="solid" property
[[1] - the indents of the first and last lines of the block are clearly shown outside the dimensions of the block
]
Multiple-line table-of-content-entry blocks are more complex than single-line blocks:
[[1] - special considerations for overhanging first and last lines of block
[[2] - negative values for indents specify outdents and allow the content to go beyond the boundaries of the box
][1] - may also specify text alignment for the body of the block
]
[Figure 5.12: Properties of blocks utilizing leaders
Two shapes of formatted table of contents entries are shown, the one on the top is a single line in length and the one on the bottom is two lines long.
The three-line entry shows an "outdent" hanging to the left on the first line and an outdent hanging to the right on the last line.
Various properties described in the text are indicated in the diagram by arrows pointing to the areas and margins created by the properties.
]
Of note:
[[1] - the last line is justified in order to grow the leader to the complete width of the last line including the outdent
 [1] - the net indents of the first and last line are the differences between the indents of the block and the respective outdents of the first and last line
]
5.4.2 Multiple leaders on a single line
[> 5.4.3][> 6.][< 5.4.1][^][^^][^^^]
When using multiple leaders on a single line, the length of each leader grows evenly in tandem:
[[1] - the length of all leaders on a single justified line is the same
 [1] - lengths grow until line is filled
 [1] - best way to push two pieces of contents to opposite ends of the line
]
Examples in samp/leader-align.fo of using one or more leaders
[Figure 5.13: Using one or more leaders on a single line
Three tests are shown.
The first test is a single line with a single leader between two strings of text. The strings of text are pushed to the outside edges of the line.
The second test shows a pattern of using "text, leader, leader, text" in two parts. The first part shows on one line: both strings of text fit on the same line with the two adjacent leaders in between. Both leaders grow and the end result has the same appearance as in the first test. The second part shows on two lines: both strings of text do not fit on the same line, so the first text and first leader are kept together on the first line and the second leader and second text are kept together so are pushed to the second line.
The third test shows two headers of a monthly calendar, where the month names are different lengths an in different languages. The first shows "MAY, leader, MAI, leader, 5". The second shows "NOVEMBER, leader, NOVEMBRE, leader, 11". In both cases the words are evenly spaced, but because of the length of the words being different, the middle words are not positioned at the same horizontal location.
]
5.4.3 Controlling the distance between leaders
[> 5.4.4][> 6.][< 5.4.2][^][^^][^^^]
The intuitive approach to controlling the distance between lines does not apply
[[1] - consider two standalone leaders that necessarily require two standalone blocks, one leader in each block as in the samp/leadlink.fo sample ([Figure 5.3]):
 [1] - the line height of the block is governed by block properties and by default is the maximum of the font size and any inline constructs found on the line
 [1] - it is intuitive to adjust the line height of the leader, but that if that line height is less than the line height of the block, there will be no change in the result because of the line height of the block will govern the placement of the leaders
]
[Figure 5.14: Controlling the distance between leaders
Two pairs of standalone leaders are shown, the top pair farther apart than the bottom pair.
The top pair illustrates a shortened line height for the leader does not impact the distance between leaders, rather, that the line height for the parent block is keeping the leaders far apart.
The bottom pair shows no specified value for the line height of the leader, but that a shortened line height for the parent block has brought the leaders close together.
]
Important to keep font size consistent when positioning adjacent lines
[[1] - leaders are drawn along the font baseline
 [1] - changing the line height does not change the font size
 [1] - changing the font size will change both the distance between the alignment point and the baseline and the height of the line in the block
 [1] - changing only the line height will not change the distance between the alignment point and the baseline
 [1] - more consistent distances are rendered when only changing one variable instead of two
]
5.4.4 <leader> Object
[> 6.][< 5.4.3][^][^^][^^^]
Purpose:
[[1] - the inline display of a rule or a sequence of characters
[[2] - object can be placed in a <[block]> object for block-level display
]]
Content:
[[1] - ([6.6.9]) (#PCDATA|[​%inline;])*
 [1] - Child object:
[[2] - [%inline;]([6.2];[Section 3.4.3 Inline-level objects])
]]
[[1] - cannot contain as a child or descendant any <[leader]>, <[inline-container]>, <[block-container]>, <[float]>, <[footnote]>, or <[marker]> objects
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
 [1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
 [1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
 [1] - [Common Font Properties]([7.9];[Section D.1.5 Common Font Properties])
 [1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
 [1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[color=]([7.18.1];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[leader-alignment=]([7.22.1];[Section D.3.3 Property summary])
[leader-length=]([7.22.4];[Section D.3.3 Property summary])
[leader-pattern=]([7.22.2];[Section D.3.3 Property summary])
[leader-pattern-width=]([7.22.3];[Section D.3.3 Property summary])
[letter-spacing=]([7.17.2];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[rule-style=]([7.22.5];[Section D.3.3 Property summary])
[rule-thickness=]([7.22.6];[Section D.3.3 Property summary])
[text-altitude=]([7.29.4];[Section D.3.3 Property summary])
[text-depth=]([7.29.5];[Section D.3.3 Property summary])
[text-shadow=]([7.17.5];[Section D.3.3 Property summary])
[visibility=]([7.30.17];[Section D.3.3 Property summary])
[word-spacing=]([7.17.8];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
Properties of note:
[[1] - the [line-height]= property of the leader does not impact the [line-height]= property of the containing block
[[2] - it may be necessary to adjust the [line-height]= property of the block to achieve the desired result
][1] - when [leader-pattern]= is "use-content" the object children of this object are replicated in whole and are not clipped to the desired length of the leader
[[2] - the actual distance covered by the leader may be shorter than desired
 [2] - using short sequences for repeated content will produce better results
]]
[Example 5-8: Leader constructs in example An excerpt from the [samp/leadlink.fo sample] ([Figure 5.3]):
01   <block font-weight="bold" font-size="16pt * 2" 
02   text-align="center">The Leader/Link/Graphic Example</block>
03   <block line-height="3px">
04   <leader leader-pattern="rule" leader-length="100%"/>
05   </block>
06   <block line-height="3px">
07   <leader leader-pattern="rule" leader-length="100%"/>
08   </block>
09   <block>
10   <leader leader-pattern="rule" leader-length="100%"/>
11   </block>
12   <block line-height="3px">
13   <leader leader-pattern="rule" leader-length="100%"/>
14   </block>
15   <block line-height="3px">
16   <leader leader-pattern="rule" leader-length="100%"/>
17   </block>
18   ...
19   <block text-align-last="justify"
20   end-indent="1cm" start-indent="1cm">
21   <basic-link internal-destination="N9">First Title</basic-link>
22   <leader leader-pattern="dots"/>
23   <basic-link internal-destination="N9">
24   <page-number-citation ref-id="N9"/>
25   </basic-link>
26   </block>
27   ...
28   <block space-before="10pt" text-align="center">
29   <leader leader-pattern="rule" leader-length="60%"/>
30   </block>
]
[Example 5-9: Complex leader example An excerpt from the [samp/leaders.fo sample] ([Figure 5.11]):
01    <block text-align-last="justify" border-style="solid" 
02   start-indent="5cm" end-indent="5cm"
03   text-indent="-2cm" last-line-end-indent="-2cm">
04   <inline>This is another very long title that will be
05  wrapping over at least three lines in order to indicate a
06  very long title</inline>
07   <leader leader-pattern="dots"/>
08   <inline>2</inline>
09   </block>
10  
11   <block text-align-last="justify"
12   start-indent="5cm" end-indent="5cm"
13   text-indent="-2cm" last-line-end-indent="-2cm">
14   <inline>This is short</inline>
15   <leader leader-pattern="dots"/>
16   <inline>3</inline>
17   </block>
18  
19   <block text-align-last="justify" text-align="justify"
20   start-indent="5cm" end-indent="5cm"
21   text-indent="-2cm" last-line-end-indent="-2cm">
22   <inline>This is a final very long title that will be
23  wrapping over at least three lines in order to indicate a
24  very long title</inline>
25   <leader leader-pattern="dots"/>
26   <inline>4</inline>
27   </block>
]


This is an accessible version of Crane's commercial training material. The content has been specifically designed to assist screen reader software in viewing the entire textual content. Figures are replaced with text narratives.

Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome: [info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect this accessible version from plagiarism, please do not make any commercial edition available to others.

+//ISBN 978-1-894049::CSL::Courses::PFUX//DOCUMENT Practical Formatting Using XSL-FO 2008-01-27 17:30UTC//EN
Practical Formatting Using XSL-FO
Seventh Edition - 2008-01-27
ISBN 978-1-894049-19-1
Copyright © Crane Softwrights Ltd.