Paged media

# 13 Paged media

Contents

## 13.1 Introduction to paged media

Paged media (e.g., paper, transparencies, pages that are displayed on computer screens, etc.) differ from continuous media in that the content of the document is split into one or more discrete pages. To handle page breaks, CSS2 extends the visual formatting model as follows:

1. The page box extends the box model to allow authors to specify page margins.
2. The page model extends the visual formatting model to account for page breaks.

The CSS 2.1 page model specifies how a document is formatted within the page box. The page box does not necessarily correspond to the real sheet where the document will ultimately be rendered (paper, transparency, screen, etc.). The user agent is responsible for transferring the page box to the sheet. Transfer possibilities include:

- Transferring one page box to one sheet (e.g., single-sided printing).
- Transferring two page boxes to both sides of the same sheet (e.g., double-sided printing).
- Transferring N (small) page boxes to one sheet (called "n-up").
- Transferring one (large) page box to N x M sheets (called "tiling").
- Creating signatures. A signature is a group of pages printed on a sheet, which, when folded and trimmed like a book, appear in their proper sequence.
- Printing one document to several output trays.
- Outputting to a file.

## 13.2 Page boxes: the @page rule

The page box is a rectangular region that contains two areas:

- The page area. The page area includes the boxes laid out on that page. The edges of the page area act as the initial containing block for layout that occurs between page breaks.
- The margin area, which surrounds the page area.

Authors can specify the margins of a page box inside an @page rule. An @page rule consists of the keyword "@page", followed by an optional page selector, followed by a block of declarations. The declarations are said to be in the page context.

The page selector specifies for which pages the declarations apply. In CSS 2.1, page selectors may designate the first page, all left pages, or all right pages

### 13.2.1 Page margins

The margin properties ('margin-top', 'margin-right', 'margin-bottom', 'margin-left', and 'margin') apply within the page context. The following diagram shows the relationships between the sheet, page box, and page margins:

[D]

Example(s):

Here is a simple example which sets all page margins on all pages:

    @page {
      margin: 3cm;
    }

The page context has no notion of fonts, so 'em' and 'ex' units are not allowed. Percentage values on the margin properties are relative to the dimensions of the page box; for left and right margins, they refer to page box width while for top and bottom margins, they refer to page box height. All other units associated with the respective CSS 2.1 properties are allowed.

Due to negative margin values (either on the page box or on elements) or absolute positioning content may end up outside the page box, but this content may be "cut" — by the user agent, the printer, or ultimately, the paper cutter.

The computed value of box margins at the top or bottom of the page area is zero.

#### Rendering page boxes that do not fit a target sheet

If a page box does not fit the target sheet dimensions, the user agent may choose to:

- Rotate the page box 90° if this will make the page box fit.
- Scale the page to fit the target.

The user agent should consult the user before performing these operations.

#### Positioning the page box on the sheet

When the page box is smaller than the target size, the user agent is free to place the page box anywhere on the sheet. However, it is recommended that the page box be centered on the sheet since this will align double-sided pages and avoid accidental loss of information that is printed near the edge of the sheet.

### 13.2.2 Page selectors: selecting left, right, and first pages

When printing double-sided documents, the page boxes on left and right pages may be different. This can be expressed through two CSS pseudo-classes that may be used in page selectors.

All pages are automatically classified by user agents into either the :left or :right pseudo-class.

Example(s):

    @page :left {
      margin-left: 4cm;
      margin-right: 3cm;
    }

    @page :right {
      margin-left: 3cm;
      margin-right: 4cm;
    }

Authors may also specify style for the first page of a document with the :first pseudo-class:

Example(s):

    @page { margin: 2cm } /* All margins set to 2cm */

    @page :first {
      margin-top: 10cm    /* Top margin on first page 10cm */
    }

Properties specified in a :left or :right @page rule override those specified in an @page rule that has no pseudo-class specified. Properties specified in a :first @page rule override those specified in :left or :right @page rules.

Margin declarations on left, right, and first pages may result in different page area widths. To simplify implementations, user agents may use a single page area width on left, right, and first pages. In this case, the page area width of the first page should be used.

### 13.2.3 Content outside the page box

When formatting content in the page model, some content may end up outside the page box. For example, an element whose 'white-space' property has the value 'pre' may generate a box that is wider than the page box. Also, when boxes are positioned absolutely, they may end up in "inconvenient" locations. For example, images may be placed on the edge of the page box or 100,000 meters below the page box.

The exact formatting of such elements lies outside the scope of this specification. However, we recommend that authors and user agents observe the following general principles concerning content outside the page box:

- Content should be allowed slightly beyond the page box to allow pages to "bleed".
- User agents should avoid generating a large number of empty page boxes to honor the positioning of elements (e.g., you don't want to print 100 blank pages).
- Authors should not position elements in inconvenient locations just to avoid rendering them.
- User agents may handle boxes positioned outside the page box in several ways, including discarding them or creating page boxes for them at the end of the document.

## 13.3 Page breaks

This section describes page breaks in CSS 2.1. Five properties indicate where the user agent may or should break pages, and on what page (left or right) the subsequent content should resume. Each page break ends layout in the current page box and causes remaining pieces of the document tree to be laid out in a new page box.

### 13.3.1 Page break properties: 'page-break-before', 'page-break-after', 'page-break-inside'

'page-break-before'

  Value: | auto | always | avoid | left | right | inherit
  Initial: | auto
  Applies to: | block-level elements
  Inherited: | no
  Percentages: | N/A
  Media: | visual, paged
  Computed value: | as specified

'page-break-after'

  Value: | auto | always | avoid | left | right | inherit
  Initial: | auto
  Applies to: | block-level elements
  Inherited: | no
  Percentages: | N/A
  Media: | visual, paged
  Computed value: | as specified

'page-break-inside'

  Value: | avoid | auto | inherit
  Initial: | auto
  Applies to: | block-level elements
  Inherited: | yes
  Percentages: | N/A
  Media: | visual, paged
  Computed value: | as specified

Values for these properties have the following meanings:

auto
  Neither force nor forbid a page break before (after, inside) the generated box.
always
  Always force a page break before (after) the generated box.
avoid
  Avoid a page break before (after, inside) the generated box.
left
  Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.
right
  Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.

Whether the first page of a document is :left or :right depends on the major writing direction of the document. A conforming user agent may interpret the values 'left' and 'right' as 'always'.

A potential page break location is typically under the influence of the parent element's 'page-break-inside' property, the 'page-break-after' property of the preceding element, and the 'page-break-before' property of the following element. When these properties have values other than 'auto', the values 'always', 'left', and 'right' take precedence over 'avoid'.

These properties only apply to block level elements that are in the normal flow of the root element.

### 13.3.2 Breaks inside elements: 'orphans', 'widows'

'orphans'

  Value: | <integer> | inherit
  Initial: | 2
  Applies to: | block-level elements
  Inherited: | yes
  Percentages: | N/A
  Media: | visual, paged
  Computed value: | as specified

'widows'

  Value: | <integer> | inherit
  Initial: | 2
  Applies to: | block-level elements
  Inherited: | yes
  Percentages: | N/A
  Media: | visual, paged
  Computed value: | as specified

The 'orphans' property specifies the minimum number of lines of a paragraph that must be left at the bottom of a page. The 'widows' property specifies the minimum number of lines of a paragraph that must be left at the top of a page. Examples of how they are used to control page breaks are given below.

For information about paragraph formatting, please consult the section on line boxes.

### 13.3.3 Allowed page breaks

In the normal flow, page breaks can occur at the following places:

1. In the vertical margin between block boxes. When a page break occurs here, the computed values of the relevant 'margin-top' and 'margin-bottom' properties are set to '0'.
2. Between line boxes inside a block box.

These breaks are subject to the following rules:

- Rule A: Breaking at (1) is allowed only if the 'page-break-after' and 'page-break-before' properties of all the elements generating boxes that meet at this margin allow it, which is when at least one of them has the value 'always', 'left', or 'right', or when all of them are 'auto'.
- Rule B: However, if all of them are 'auto' and the nearest common ancestor of all the elements has a 'page-break-inside' value of 'avoid', then breaking here is not allowed.
- Rule C: Breaking at (2) is allowed only if the number of line boxes between the break and the start of the enclosing block box is the value of 'orphans' or more, and the number of line boxes between the break and the end of the box is the value of 'widows' or more.
- Rule D: In addition, breaking at (2) is allowed only if the 'page-break-inside' property is 'auto'.

If the above doesn't provide enough break points to keep content from overflowing the page boxes, then rules B and D are dropped in order to find additional breakpoints.

If that still does not lead to sufficient break points, rules A and C are dropped as well, to find still more break points.

### 13.3.4 Forced page breaks

A page break must occur at (1) if, among the 'page-break-after' and 'page-break-before' properties of all the elements generating boxes that meet at this margin, there is at least one with the value 'always', 'left', or 'right'.

### 13.3.5 "Best" page breaks

CSS2 does not define which of a set of allowed page breaks must be used; CSS2 does not forbid a user agent from breaking at every possible break point, or not to break at all. But CSS2 does recommend that user agents observe the following heuristics (while recognizing that they are sometimes contradictory):

- Break as few times as possible.
- Make all pages that don't end with a forced break appear to have about the same height.
- Avoid breaking inside a block that has a border.
- Avoid breaking inside a table.
- Avoid breaking inside a floated element

Example(s):

Suppose, for example, that the style sheet contains 'orphans: 4', 'widows: 2', and there are 20 lines (line boxes) available at the bottom of the current page:

- If a paragraph at the end of the current page contains 20 lines or fewer, it should be placed on the current page.
- If the paragraph contains 21 or 22 lines, the second part of the paragraph must not violate the 'widows' constraint, and so the second part must contain exactly two lines
- If the paragraph contains 23 lines or more, the first part should contain 20 lines and the second part the remaining lines.

Now suppose that 'orphans' is '10', 'widows' is '20', and there are 8 lines available at the bottom of the current page:

- If a paragraph at the end of the current page contains 8 lines or fewer, it should be placed on the current page.
- If the paragraph contains 9 lines or more, it cannot be split (that would violate the orphan constraint), so it should move as a block to the next page.

## 13.4 Cascading in the page context

Declarations in the page context obey the cascade just like normal CSS2 declarations.

Example(s):

Consider the following example:

    @page {
      margin-left: 3cm;
    }

    @page :left {
      margin-left: 4cm;
    }

Due to the higher specificity of the pseudo-class selector, the left margin on left pages will be '4cm' and all other pages (i.e., the right pages) will have a left margin of '3cm'.