css2/page.src

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<!-- $Id: page.src,v 2.73 2011-10-18 19:25:27 bbos Exp $ -->
<HEAD>
<TITLE>Paged media</TITLE>
<!--script src="http://www.w3c-test.org/css/harness/annotate.js#CSS21_DEV" type="text/javascript" defer></script-->
</HEAD> 

<body>
<h1><a name="the-page">Paged media</a></h1>

<h2><a name="page-intro">Introduction to paged media</a></h2>

<p>Paged media (e.g., paper, transparencies, pages that are displayed
on computer screens, etc.) differ from <a
href="./media.html#continuous-media-group">continuous media</a> in
that the content of the document is split into one or more discrete
pages. To handle pages, CSS&nbsp;2 describes how page margins are set
on <a href="#page-box">page boxes</a>, and how <a href="#page-breaks">page breaks</a> are declared.

<p>The user agent is responsible for transferring the page boxes of a
document onto the real <span class="index-def"
title="sheet"><dfn>sheets</dfn></span> where the document will
ultimately be rendered (paper, transparency, screen, etc.). There is
often a 1-to-1 relationship between a page box and a sheet, but this
is not always the case. Transfer possibilities include:</P>

<ul>
<li>Transferring one page box to one sheet (e.g., single-sided printing).
<li>Transferring two page boxes to both sides of the same sheet (e.g.,
double-sided printing).
<li>Transferring N (small) page boxes to one sheet (called "n-up").
<li>Transferring one (large) page box to N x M sheets (called "tiling").
<li>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.
<li>Printing one document to several output trays.
<li>Outputting to a file.
</ul>


<h2><a name="page-box">Page boxes</a>: the @page rule</h2>

<p>The <span class="index-def" title="page box"><dfn>page
box</dfn></span> is a rectangular region that contains two areas:</p>

<ul>

<li>The <span class="index-def" title="page area"><a
name="page-area"><dfn>page area</dfn></a></span>. The page area
includes the boxes laid out on that page. The edges of the first page
area establish the rectangle that is the initial <a
href="visudet.html#containing-block-details">containing block</a> of
the document.
The canvas background is painted within and covers the page area.


<li>The margin area, which surrounds the page area. 
The page margin area is transparent.
</ul>

<p>The size of a page box cannot be specified in CSS&nbsp;2.

<P>Authors can specify the margins of a page box inside an <span
class="index-def" title="@page">@page</span> rule. An @page rule
consists of the keyword "@page", followed by an optional page
selector, followed by a block containing declarations and
at-rules. Comments and white space are allowed, but optional, between
the @page token and the page selector and between the page selector
and the block. The declarations in an
@page rule are said to be in the <span class="index-def"
title="page-context"><a name="page-context"><dfn>page
context</dfn></a></span>.</p>

<p class=note>Note: CSS level&nbsp;2 has no at-rules that may appear
inside @page, but such at-rules are expected to be defined in
level&nbsp;3.

<P>The <span class="index-def" title="page selector"><dfn>page
selector</dfn></span> specifies for which pages the declarations
apply. In CSS&nbsp;2, page selectors may designate the first page,
all left pages, or all right pages</p>

<P>The rules for handling malformed declarations, malformed
statements, and invalid at-rules inside @page are as defined in <a
href="syndata.html#parsing-errors">section&nbsp;4.2,</a> with the
following addition: when the UA expects the start of a declaration or
at-rule (i.e., an IDENT token or an ATKEYWORD token) but finds an
unexpected token instead, that token is considered to be the first
token of a malformed declaration. I.e., the rule for malformed
declarations, rather than malformed statements is used to determine
which tokens to ignore in that case.

<h3><a name="page-margins">Page margins</a></h3>

<P>In CSS&nbsp;2, only the <a href="box.html#margin-properties">margin
properties</a> (<span class="propinst-margin-top">'margin-top'</span>,
<span class="propinst-margin-right">'margin-right'</span>, <span
class="propinst-margin-bottom">'margin-bottom'</span>, <span
class="propinst-margin-left">'margin-left'</span>, and <span
class="propinst-margin">'margin'</span>) apply within the <a
href="#page-context">page context</a>. The following diagram shows the
relationships between the sheet, page box, and page margins:</P>

<div class="figure">
<P><img src="./images/page-info.png" alt="Illustration of sheet, page
box, margin, and page area."></p>
</div>

<div class="example"><P>
Here is a simple example which sets all page margins on all pages:

<pre>
@page {
  margin: 3cm;
}
</pre>
</div>

<p>The <a href="#page-context">page context</a> 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 <a
href="#page-box">page box</a>; for left and right margins, they refer
to the width of the page box while for top and bottom margins, they
refer to the height of the page box. All other units associated with
the respective CSS&nbsp;2 properties are allowed.

<P>Due to negative margin values (either on the page box or on
elements) or <a href="visuren.html#absolute-positioning">absolute
positioning</a> content may end up outside the page box, but this
content may be "cut" &mdash; by the user agent, the printer, or ultimately,
the paper cutter.


<!--
<h4><a name="oversized-page-box">[This section intentionally left blank]</a></h4>


<h4><a name="positioning-page-box">[This section intentionally left blank]</a></h4>
-->


<h3><a name="page-selectors">Page selectors: selecting left, right, and first pages</a></H3>

<P>When printing double-sided documents, the <a href="#page-box">page
boxes</a> on left and right pages may be different. This can be
expressed through two CSS pseudo-classes that may be used in page selectors.

<P>All pages are automatically classified by user agents into either
the <span class="index-def"
title=":left|pseudo-class:::left">:left</span> or <span
class="index-def" title=":right|pseudo-class:::right">:right</span>
pseudo-class.
Whether the first page of a document is :left or :right depends on the
major writing direction of the root element. For example, the first
page of a document with a left-to-right major writing direction would
be a :right page, and the first page of a document with a
right-to-left major writing direction would be a :left page. To
explicitly force a document to begin printing on a left or right page,
authors can <a href="#page-break-props">insert a page break</a> before
the first generated box.

<div class="example"><P>
<PRE>
@page :left {
  margin-left: 4cm;
  margin-right: 3cm;
}

@page :right {
  margin-left: 3cm;
  margin-right: 4cm;
}
</PRE>
</div>

<p>If different declarations have been given for left and right pages,
the user agent must honor these declarations even if the user agent
does not transfer the page boxes to left and right sheets (e.g., a
printer that only prints single-sided). 

<P>Authors may also specify style for the first page of a document
with the <span class="index-def"
title=":first|pseudo-class:::first">:first</span> pseudo-class:

<div class="example"><P>
<PRE>
@page { margin: 2cm } /* All margins set to 2cm */

@page :first {
  margin-top: 10cm    /* Top margin on first page 10cm */
}
</PRE>
</div>

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

<p>If a <a href="#forced">forced break</a> occurs before the first
generated box, it is undefined in CSS&nbsp;2 whether ':first'
applies to the blank page before the break or to the page after it.

<P>Margin declarations on left, right, and first pages may result in
different <a href="#page-area">page area</a> 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.


<h3> <a name="outside-page-box">Content outside the page box</a></h3>

<P>When formatting content in the page model, some content may end up
outside the current page box. For example, an element whose <span
class="propinst-white-space">'white-space'</span> property has the
value 'pre' may generate a box that is wider than the page box. As
another example, when boxes are positioned absolutely or relatively,
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.

<P>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:</p>

<ul>

<li>Content should be allowed slightly beyond the page box to allow
pages to "bleed".

<li>User agents should avoid generating a large number of empty page
boxes to honor the positioning of elements (e.g., you do not want to
print 100 blank pages).

<li>Authors should not position elements in inconvenient locations
just to avoid rendering them. 

<li>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.
</ul>

<H2><a name="page-breaks">Page breaks</a></H2>

<P>This section describes page breaks in CSS&nbsp;2. 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 <a href="#page-box">page
box</a> and causes remaining pieces of the <a
href="conform.html#doctree">document tree</a> to be laid out in a new
page box.

<h3><a name="page-break-props">Page break properties</a>: <span
class="propinst-page-break-before">'page-break-before'</span>,
<span class="propinst-page-break-after">'page-break-after'</span>,
<span class="propinst-page-break-inside">'page-break-inside'</span>
</h3>

<!-- #include src=properties/page-break-before.srb -->

<!-- #include src=properties/page-break-after.srb -->

<!-- #include src=properties/page-break-inside.srb -->

<P>Values for these properties have the following meanings:</p>

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

<p>A conforming user agent
may interpret the values 'left' and 'right' as 'always'.

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

<p>User Agents must apply these properties to block-level elements
in the normal flow of the root element. User agents may also apply
these properties to other elements, e.g., 'table-row' elements.

<p>When a page break splits a box, the box's margins, borders, and
padding have no visual effect where the split occurs.


<h3><a name="break-inside">Breaks inside elements</a>: <span
class="propinst-orphans">'orphans'</span>, <span
class="propinst-widows">'widows'</span></h3>

<!-- #include src=properties/orphans.srb -->

<!-- #include src=properties/widows.srb -->

<P>The <span class="propinst-orphans">'orphans'</span> property
specifies the minimum number of lines in a block container that must be left
at the bottom of a page. The <span class="propinst-widows">'widows'</span> property specifies the minimum
number of lines in a block container that must be left at the top of a page.
Examples of how they are used to control page breaks are given below.

<p>Only positive values are allowed.

<P>For information about paragraph formatting, please consult the
section on <a href="visuren.html#line-box">line boxes</a>.

<h3><a name="allowed-page-breaks">Allowed page breaks</a></h3>

<p>In the normal flow, page breaks can occur at the following places:</p>

<ol>
<li>
In the vertical margin between block-level boxes. When an unforced page
break occurs here, the <a href="cascade.html#used-value">used
values</a> of the relevant <span
class="propinst-margin-top">'margin-top'</span> and <span
class="propinst-margin-bottom">'margin-bottom'</span> properties are
set to '0'. When a forced page break occurs here, the used value of
the relevant <span
class="propinst-margin-bottom">'margin-bottom'</span> property is set
to '0'; the relevant <span
class="propinst-margin-top">'margin-top'</span> used value may either
be set to '0' or retained.

<li>Between <a href="visuren.html#line-box">line boxes</a>
inside a <a href="visuren.html#block-boxes">block container</a> box.

<li>Between the content edge of a block container box and the outer edges of its
child content (margin edges of block-level children or line box edges
for inline-level children) if there is a (non-zero) gap between them.
</ol>

<p class=note>Note: It is expected that CSS3 will specify that the
relevant 'margin-top' applies (i.e., is not set to '0') after a forced
page break.

<!-- What about line boxes next to a float? -IJ -->

<p>These breaks are subject to the following rules:

<ul>
<li><strong>Rule A:</strong> Breaking at (1) is allowed only if the <span
class="propinst-page-break-after">'page-break-after'</span> and <span
class="propinst-page-break-before">'page-break-before'</span> 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'.

<li><strong>Rule B:</strong> However, if all of them are 'auto' and
a common ancestor of all the elements has a <span
class="propinst-page-break-inside">'page-break-inside'</span> value of
'avoid', then breaking here is not allowed.

<li>
<strong>Rule C:</strong> Breaking at (2) is allowed only if the number of <a
href="visuren.html#line-box">line boxes</a> between the
break and the start of the enclosing block box is 
the value of <span
class="propinst-orphans">'orphans'</span> or more, and the number of
line boxes between the break and the end of the box is 
the value of <span class="propinst-widows">'widows'</span> or more.

<li><strong>Rule D:</strong> In addition, breaking at (2) or (3) is
allowed only if the <span
class="propinst-page-break-inside">'page-break-inside'</span> property
of the element and all its ancestors is 'auto'.
</ul>

<p>If the above does not provide enough break points to keep content
from overflowing the page boxes, then rules A, B and D are dropped in
order to find additional breakpoints.

<p>If that still does not lead to sufficient break points, rule
C is dropped as well, to find still more break points.


<h3><a name="forced">Forced page breaks</a></h3>

<p>A page break <em>must</em> occur at (1) if, among the <span
class="propinst-page-break-after">'page-break-after'</span> and <span
class="propinst-page-break-before">'page-break-before'</span>
properties of all the elements generating boxes that meet at this
margin, there is at least one with the value 'always', 'left', or
'right'.

<h3><a name="best-page-breaks">"Best" page breaks</a></h3>

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

<ul>
<li>Break as few times as possible.
<li>Make all pages that do not end with a forced break appear to have about
the same height.
<li>Avoid breaking inside a replaced element.
</ul>

<div class="example"><P> 
Suppose, for example, that the style sheet 
contains 'orphans: 4', 'widows: 2', and
there are 20 lines (<a href="visuren.html#line-box">line boxes</a>)
available at the bottom of the current page:</p>

<ul>

<li>If a paragraph at the end of the current page contains 20 lines or fewer,
it should be placed on the current page.

<li>If the paragraph contains 21 or 22 lines, the second part of the
paragraph must not violate the <span
class="propinst-widows">'widows'</span> constraint, and so the
second part must contain exactly two lines

<li>If the paragraph contains 23 lines or more, the first part should
contain 20 lines and the second part the remaining lines.
						    
</ul>

<P>Now suppose that <span class="propinst-orphans">'orphans'</span> is
'10',
<span class="propinst-widows">'widows'</span> is '20', 
and there are 8 lines available at the bottom of the current page:</p>

<ul>

<li>If a paragraph at the end of the current page contains 8 lines or
fewer, it should be placed on the current page.

<li>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.
</ul>
</div>

<h2><a name="page-cascade">Cascading in the page context</a></H2>

<P>Declarations in the <a href="#page-context">page context</a> obey
the <a href="cascade.html">cascade</a> just like normal CSS
declarations.

<div class="example"><P>
Consider the following example:

<PRE>
@page {
  margin-left: 3cm;
}

@page :left {
  margin-left: 4cm;
}
</PRE>

<P>Due to the <a href="cascade.html#cascading-order">higher
specificity</a> 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'.
</div>
</body>
</html>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-declaration:"~/SGML/HTML4.decl"
sgml-default-doctype-name:"html"
sgml-minimize-attributes:t
sgml-nofill-elements:("pre" "style" "br")
sgml-live-element-indicator:t
End:
-->