5.1 Lists

5.1.1 Aligned pairs of block-level constructs

Standalone blocks cannot be adjacent to each other in the inline-progression direction.

• A block-level construct typically continues the block-progression direction.

Pairs of adjacent blocks are useful to associate the information in one of the blocks to the information in the other block. This includes

• side-by-side language text, e.g.:

  • aligned translation paragraphs,

• terms and their definitions,

• generic list item formatting, i.e.:

  • the item enumerator and the item content.

The name of the construct shouldn't prejudice how the construct is used.

• Don't think that only lists in your XML information can use this construct for layout.

• Regard the construct as a layout facility for pairs of block-level constructs in the inline-progression direction of the parent block.

• A two-column table construct may suffice or offer other layout features you need.

Specialized properties are available for the behaviors characteristic of list processing.

• 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.

• There is no obligation to use the specialized properties.

The content of the blocks does not impact the start/end edges of the blocks.

• 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.

• The edges are fixed to the same values for all members of the entire list.

  • Planning ahead is necessary to ensure any undesired wrapping within edges is avoided.

5.1.2 List constructs

A list is a block-level object shown in two different ways in Figure 5-3.

• It contains only list items (pairs).

  • It requires a nested list to itself be a list item unless it is already in a list item.

• When using provisional values and functions, the edges are fixed to the same values for all members of the entire list.

  • Planning ahead is necessary to ensure any undesired wrapping within edges is avoided.

• When specifying margins on a per list item basis, the edges can be explicitly specified differently from other list items.

  • One cannot measure the content of a label or body in order to set the margins relative to the content.

Figure 5-3. The blocks of information that comprise a list

Block alignment can involve more than two blocks, as shown in Figure 5-4.

• The body of a list item can itself contain a list with two aligned blocks.

• The initial value of relative alignment is the before edge for all blocks.

Figure 5-4. Aligning more than two blocks

Consider using a table for more than two blocks.

• Table properties allow the block widths to be proportional.

• Table cells do not overlap.

Horizontal indentation of the list item components is the responsibility of the stylesheet writer.

• The item label's start-indent is specified explicitly (or inherited).

• The item body's end-indent is specified explicitly (or inherited).

• The item label's end-indent and item body's start-indent can be set independently.

  • Without proper planning, this can inadvertently result in display problems, e.g.:

    • overlapping label content on top of body content,

    • undesired wrapping of label content.

• The item label's end-indent and item body's start-indent can be set relative to the start-indent of the item label.

  • The stylesheet can ask the processor to dynamically set these values on a per list item basis.

  • This protects the content of the two areas from sharing the same place on the rendered output.

Vertical alignment of list item label defaults to a common before edge.

• This ensures that the before edge of the first block on each side is aligned on the page.

• relative-align can be set to common text baseline of first lines;

  • when different font sizes are used without aligning to the text baseline, the smaller of the two font sizes will appear to be superscripted.

You are not obliged to use body-start() or label-end() .

• You can specify the distances from the parent edges explicitly for each of the labels and bodies, as shown in Figure 5-5.

  Figure 5-5. Simple adjacent blocks in a list

  

Risk of overlap is borne by the stylesheet writer.

• 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.

• Another common error is to change, after writing a stylesheet, the page width and not think to change the list item member indents;

  • e.g., when narrowing the page from US letter to A4 format, the blocks could overlap in the middle when the distances from the edges are used.

Using body-start() or label-end() will prevent edges from overlapping, as shown in Figure 5-6.

Figure 5-6. Basic edges on relative calculations

Indentation of the list item components can be relative.

• Processor notes provisional-distance-between-starts and provisional-label-separation values for built-in functions.

  • The term "provisional" indicates the value is used as part of an arithmetic calculation.

  • These values are properties of the list as a whole and cannot be set on an individual item.

  • Specifying a separation prevents overlapping of the label and body.

• 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 running into each other.

  • label-end() :

    • is the distance from the end of the label to the end of the line accommodating the indent of the label,

    • is used as the value for the end-indent property of the item label;

  • body-start() :

    • is the distance from the start of the line to the start of the body accommodating the indent of the item label,

    • is used as the start-indent property of the item body.

5.1.3 Nested list constructs

The nesting of lists may require the use of hidden list item members.

• A nested list in the user 's XML vocabulary is usually one of either:

  • a block within an existing list item;

    • an example is list/listitem/list ;

    • the block-level list-block formatting object can flow with other blocks inside a list-item-body ,

  • its own list item;

    • an example is list/list ;

    • this requires a hidden list-item within which the list block is placed in the body;

    • a list-block can only contain list-item children;

    • the hidden list-item children must have blocks for labels;

      • the label blocks can be empty to hide the fact they are list items.

The choice of one of these depends on:

• the need for dependence of the indentation of the nested list;

  • is its indentation fixed?

    • use the body of a hidden list item with a fixed indentation for the body;

  • is its indentation relative to the indentation of the label of the list item in which it is flowed ?

    • use the calculated body start indentation of the preceding list item,

• the nature of the source list;

  • is the nested list inside one of the list items (typical; e.g. HTML, DocBook)?

     Line 01 <list>      02   <item>      03     <p>...</p>      04     <list>  nested list  </list>      05   </item>      06   <item>... 

  • is the nested list a sibling of other list items (atypical)?

     Line 01 <list>      02   <item>      03     <p>...</p>      04   </item>      05   <list>  nested list  </list>      06   <item>... 

The use of a ghost list item, shown in Figure 5-7, prevents violating the content model rules for the containing list.

Figure 5-7. Two methods of nesting a list

You cannot use just a block or list-block in this situation.

• A list-block can only contain list-item children.

• The ghost list item contains the nested list in the body of the item.

  • It requires an empty block in the label to not be visible on the page.

5.1.4 The list-block object

Purpose

• This is the parent object of a related set of pairs of aligned block-level areas laid out in the inline-progression direction.

Content

• ( 6.8.2 ) (list-item+) ,

• child object:

  • list-item ( 6.8.3 ; 133),

• any number of marker children at the beginning.

Property sets

• Common accessibility properties ( 7.4 ; 326),

• common aural properties ( 7.6 ; 327),

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

• common margin properties block ( 7.10 ; 332),

• common relative position properties ( 7.12 ; 333).

Other optional properties

• break-after ( 7.19.1 ; 366),

• break-before ( 7.19.2 ; 367),

• id ( 7.28.2 ; 384),

• intrusion- displace ( 7.18.3 ; 385),

• keep-together ( 7.19.3 ; 386),

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

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

• provisional-distance-between-starts ( 7.28.4 ; 406),

• provisional-label-separation ( 7.28.3 ; 407).

Shorthands influencing the above properties

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

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

• page-break-inside ( 7.29.18 ; 402).

Properties of interest

• provisional-distance-between-starts specifies the desired distance between the start of the list item label and the start of the list item body;

• provisional-label-separation specifies the desired distance between the end of the list item label and the start of the list item body.

A list-block construct from the earlier Figure 2-8 is shown in Example 5-1.

Separation between the label and body is specified;

• the label is .33 inches wide and .1 inches away from the body.

Example 5-1 The list block

 Line 01 <block space-before.optimum="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.optimum="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.5 The list-item object

Purpose

• This is the parent of a single pair of aligned block-level areas laid out in the inline-progression direction.

  • Indents are relative to containing list-block object.

Content

• ( 6.8.3 ) ( list-item-label, list-item-body),

• child objects (listed alphabetically ):

  • list-item-body ( 6.8.4 ; 136),

  • list-item-label ( 6.8.5 ; 134),

• referring object:

  • list-block ( 6.8.2 ; 131),

• any number of marker children at the beginning.

Property sets

• Common accessibility properties ( 7.4 ; 326),

• common aural properties ( 7.6 ; 327),

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

• common margin properties block ( 7.10 ; 332),

• common relative position properties ( 7.12 ; 333).

Other optional properties

• break-after ( 7.19.1 ; 366),

• break-before ( 7.19.2 ; 367),

• id ( 7.28.2 ; 384),

• intrusion-displace ( 7.18.3 ; 385),

• keep-together ( 7.19.3 ; 386),

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

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

• relative-align ( 7.13.6 ; 408).

Shorthands influencing the above properties

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

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

• page-break-inside ( 7.29.18 ; 402).

Properties of interest

• 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;

  • the value " baseline " is typically used when both sides are using text;

  • the value " before " is typically used when one or both sides are graphics.

A list-item construct from the earlier Section 2.2.2 is shown in Example 5-2.

5.1.6 The list-item-label object

Purpose

• This is the start-side member of a pair of aligned block-level areas laid out in the inline-progression direction.

Content

• ( 6.8.5 ) (%block;)+ ,

• child object:

  • %block; ( 6.2 ; 69),

Example 5-2 The list item

 Line 01 <block space-before.optimum="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.optimum="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> 

• referring object:

  • list-item ( 6.8.3 ; 133),

• any number of marker children at the beginning.

Property sets

• Common accessibility properties ( 7.4 ; 326).

Other optional properties

• id ( 7.28.2 ; 384),

• keep-together ( 7.19.3 ; 386).

Shorthand influencing the above properties

• page-break-inside ( 7.29.18 ; 402).

Property of interest

• end-indent can utilize the label-end() function.

A list-item-label construct from the earlier Section 2.2.2 is shown in Example 5-3.

Of note:

• the end alignment is specified on the label to move the content of the label as close as possible to the body;

• this supports the appearance of variable length labels (i.e. Roman characters ) with a common distance between the label and the body.

Example 5-3 The list item's label

 Line 01 <block space-before.optimum="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.optimum="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       12       <block font-size="14pt">excerpts of formatting objects created      13              through the use of an XSLT stylesheet</block>      14     </list-item-body>      15   </list-item>      16 </list-block> 

5.1.7 The list-item-body object

Purpose

• This is the end-side member of a pair of aligned block-level areas laid out in the inline-progression direction.

Content

• ( 6.8.4 ) (%block;)+ ,

• child object:

  • %block; ( 6.2 ; 69),

• referring object:

  • list-item ( 6.8.3 ; 133),

• any number of marker children at the beginning.

Property sets

• Common accessibility properties ( 7.4 ; 326).

Other optional properties

• id ( 7.28.2 ; 384),

• keep-together ( 7.19.3 ; 386).

Shorthand influencing the above properties

• page-break-inside ( 7.29.18 ; 402).

Property of interest

• start-indent can utilize the body-start() function.

A list-item-body construct from the earlier Section 2.2.2 is shown in Example 5-4.

Example 5-4 The list item's body

 Line 01 <block space-before.optimum="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.optimum="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?

Some formatting requirements for lists cannot be satisfied with the list-block construct.

• You are not obliged to use list-block to format a list-like source construct.

• list-block forces the stylesheet writer to specify the start and end edges of the labels and bodies of the items, which may not be what is desired.

Figure 5-8 shows three alternative approaches to formatting three list items where the item labels have distinctly different lengths, none of which is known by the stylesheet writer.

Figure 5-8. Three alternatives to using a list construct for a list

One approach is basing the indentation of all item bodies on the longest length of all item labels.

• You can use one table for entire list contents (Figure 5-8, left);

  • hidden borders and auto-calculated column widths in all rows reflect a single set of column widths;

  • use one row for each list item, with auto width calculation of the first column determining longest label;

    • it may not work well if the label has spaces that will promote cell balancing.

Another approach is basing the indentation of each item body on the length of corresponding item labels.

• You can use a one-row table for each list item (Figure 5-8, center);

  • use hidden borders and auto-calculated column widths for each individual row in separate table;

  • use as many tables as there are list items.

• You can use a side float aligned with the block (Figure 5-8, right);

  • each body block is prefaced with a side float block with the label whose size squeezes the body block width.