csswg-drafts/css3-page/Overview.src.html at 6b6542523d03f1d0900cc0be83875fc773482fdc · w3c/csswg-drafts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
63
23CB
0
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
<title>
CSS Paged Media Module Level 3
</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="../default.css" rel="stylesheet" type="text/css">
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
<style type="text/css">
  .keyword { font-weight:bold }
  .equation { padding: 2% }
  table.equation {text-align:center}
  td, th { vertical-align: top }
  pre { font-size: 1em; }

  #margin-values { border-collapse: collapse; }
  #margin-values td,
  #margin-values th
  {
                padding: 0.2em;
                border: thin solid black;
  }

  .property-list
  {
                border: 1px solid black;
                padding: .2em;
                margin-top: 2em;
  }

  .property-list td
  {
                border: 1px solid black;
                padding: .1em;
  }

  .editorial
  {
                display: block;
                font-family: arial, helvetica, sans-serif;
      font-size: 80%;
      margin-left: .5in;
      margin-right: 1in ;
      padding: 0.125in;
      background: #FFFFDD ;
  }

  .editorial:after { content: "Ed."}
  .RFC2119
  {
                text-transform: lowercase;
                font-style: italic
  }

  em em.RFC2119
  {
                text-transform: lowercase;
                font-style: normal
  }

  table.page-sizes
  {
                border: thin solid;
                margin-top: 1.5em;
  }
  table.page-sizes td
  {
                border: thin solid;
                padding: .5em;
  }
  table.page-sizes th
  {
                border: thin solid;
                padding: .5em;
                background: #ffffaa;
  }

</style>
</head>
<body>
<div>
<div class="head">
<!--logo-->
<h1>CSS Paged Media Module Level 3</h1>
<h2 class="no-num no-toc" id="w3c-working">[LONGSTATUS] [DATE]</h2>
<dl>
  <dt>This version:</dt>    <dd><a href="http://dev.w3.org/csswg/css3-page/">http://dev.w3.org/csswg/css3-page/</a></dd>
    <!-- <dd><a href="[VERSION]">http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]</a></dd> -->
  <dt>Latest version:</dt>    <dd><a href="http://www.w3.org/TR/css3-page">http://www.w3.org/TR/css3-page</a></dd>
  <dt>Previous version:</dt>    <dd><a href="http://www.w3.org/TR/2004/CR-css3-page-20040225/">http://www.w3.org/TR/2004/CR-css3-page-20040225/</a></dd>
  <dt>Editors:</dt>    <dd>Melinda Grant, Hewlett-Packard</dd>
    <dd>H&aring;kon Wium Lie, Opera Software</dd>
    <dd>Elika J. Etemad, Hewlett-Packard</dd>
</dl>

<!--copyright-->

</div>
<hr title="Separator for header">

<h2 class="no-num no-toc" id="abstract">Abstract</h2>

<p>This module describes the page model that partitions a flow into pages. It
builds on the <a href="/TR/CSS21/box.html">Box model module</a> and introduces
and defines the page model and paged media. It adds functionality for
pagination, page margins, page size and orientation, headers and footers,
widows and orphans, and image orientation. Finally it extends generated content
to enable page numbering and running headers / footers.</p>

<!-- "Status of this document" -->

<h2 class="no-num no-toc" id="status">Status of this Document</h2>

<!--status-->
<p>This document contains the <abbr title="Cascading Style Sheets">CSS3</abbr>
Paged Media Module W3C Last Call <a href="/2005/10/Process-20051014/tr.html#RecsWD">Working Draft</a> of [DATE]. The
Last Call period ends on <span class="fudge">TBD</span>.</p>

<p>Relative to the previous Last Call Working Draft, this version has dropped
the formerly named 'fit' and 'fit-position' properties; they are
renamed to 'object-fit' and 'object-position', redefined to enable additional
use cases, and moved to the
  <a href="http://www.w3.org/TR/css3-images/">CSS3 Image Values and Replaced Content module</a>.
The margin-box sizing algorithm has been reworded to be a bit simpler,
and many miscellaneous clarifications and editorial improvements have
been incorporated.</p>

<p>Features at-risk (may be removed if they lack implementor interest):</p>
<ul>
  <li>comma-separated page selectors
</ul>

<p>Expected next revision to this document is another LCWD, due to the
substantive changes to margin box sizing and other areas that are now
specified with more precision.</p>

<p>The <a href="lc2_issues.htm">Disposition of Comments</a>
document contains the current issues list and responses to input received
during this Last Call period.</p>

<h2 class="no-num no-toc" id="contents">Table of Contents</h2><!--begin-toc-->
<!--end-toc-->
<!-- "Introduction" -->
<h2 id="intro">Introduction</h2>

<p>Paged media (e.g., paper, transparencies, photo album pages, pages
displayed on computer screens as printed output simulations) differ from
<a href="/TR/CSS2/media.html#continuous-media-group">continuous media</a>
in that the content of the document is split into one or more discrete
static display surfaces. To handle pages, CSS3 Paged Media describes how:</p>

<ul>
  <li><a href="#page-breaks">page breaks</a> are created and avoided;</li>
  <li>the page properties such as size, orientation, margins, border, and
  padding are specified;</li>
  <li>headers and footers are established within the page margins;</li>
  <li>content such as page counters are placed in the headers and footers; and</li>
  <li>orphans and widows can be controlled.</li>
</ul>

<p>This module defines a <a href="#page-model">page model</a> that specifies how a
document is formatted within a rectangular area, called the
<a href="#page-box-page-rule">page box</a>, that has finite width and height.

<p>Although CSS3 does not specify how user agents transfer page boxes to sheets,
it does include certain mechanisms for telling user agents about the intended
page sheet <a href="#page-size">size and orientation</a>. In the general case,
CSS3 assumes that one page box will be transferred to one surface of similar
size.</p>

<p>All properties defined in this specification also accept the
<a href="http://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">inherit</a>
keyword as their value, but for readability it has not been listed explicitly.

<h2 id="conformance">Conformance</h2>

<p>All of the text in this specification is normative except sections
explicitly marked as non-normative, examples, and notes. The keywords
"<em class="RFC2119">MUST</em>", "<em class="RFC2119">SHALL</em>",
"<em class="RFC2119">MUST NOT</em>", "<em class="RFC2119">SHALL NOT</em>",
"<em class="RFC2119">REQUIRED</em>", "<em class="RFC2119">SHOULD</em>",
"<em class="RFC2119">SHOULD NOT</em>", "<em class="RFC2119">RECOMMENDED</em>",
"<em class="RFC2119">MAY</em>", and "<em class="RFC2119">OPTIONAL</em>" when
used in this document are to be interpreted as described in <cite>RFC
2119</cite> [[!RFC2119]]. However, for readability, these words do not appear
in all uppercase letters in this specification.</p>

<p>Examples in this specification are introduced with the words "for example"
  or are set apart from the normative text with <code>class="example"</code>,
  like this:

<div class="example">
  <p>This is an example of an informative example.</p>
</div>

<p>Informative notes begin with the word "Note" and are set apart from the
  normative text with <code>class="note"</code>, like this:

<p class="note">Note, this is an informative note.</p>

<h2 id="page-terms">Page Terminology</h2>

<p>The following terminology and accompanying diagrams help to describe the
page model:</p>

<dl>
  <dt id="page-sheet">Page sheet</dt>
  <dd><img src="PageSheet.png" style="float: right;" alt="The corner of a page sheet with the non-printable area at the edge and printable area inside it"
  height="148" width="194">The page sheet is one surface of the physical
  medium. The illustration to the right shows a representation of the upper-left
  corner of a page sheet.</dd>

  <dt id="printable-area">Printable and non-printable areas</dt>
  <dd>The non-printable area is the area of a page sheet that a physical device such
  as a printer is not capable of marking reliably, usually due to the printer's
  paper handling mechanism. This value is printer dependent and is usually a
  small region along each edge of the page sheet. The printable area is the area
  of page sheet that a printer <em>is</em> capable of marking reliably. The size
  of the printable area is the size of the page sheet reduced by the size of the
  non-printable area. A user agent may not know the dimensions of this area for a
  particular printing device; but when its dimensions are known, user agents
  <em class="RFC2119">MAY</em> adjust the formatting of the document so that
  content falls within the printable area. How this adjustment is accomplished is
  device dependent within the constraints expressed in the sections <a href="#renderingpages">Rendering page boxes that do not fit a page sheet</a> and
  <a href="#content-outside-box">Content outside the page box</a>.</dd>

  <dt id="page-orientation">Page Orientation</dt>
  <dd>The page orientation is defined by comparing the length of the edges of a
  <a href="#page-box">page box</a>. The page box is a rectangle with two
  perpendicular edges called the long edge and the short edge. The length of the
  long edge is always greater than or equal to the length of the short edge. When
  the page box is square, the two edges are of the same length and either can be
  used as the long edge with the other being the short edge. This specification
  defines page orientations of 'portrait' and 'landscape'.</dd>

  <dt id="portrait">Portrait Orientation</dt>
  <dd>A portrait page's height is greater than or equal to its width. Horizontal
  elements are parallel to the short edge and vertical elements to the long edge.</dd>

  <dt id="landscape">Landscape Orientation</dt>
  <dd>A landscape page's width is greater than or equal to its height. Horizontal
  elements are parallel to the long edge and vertical elements to the short edge.
  <span class="note">Note that CSS3 makes no distinction between landscape and
  reverse-landscape orientations. However, future versions of CSS may do so.
  UAs should consider, when formatting for duplexed printing, the binding edge,
  page progression, and ease of reading when choosing between landscape and
  reverse-landscape renderings.</span>
  </dd>

  <dt id="duplex-printing">Duplex Printing</dt>
  <dd>Duplex printing prints one page box per side of a page sheet and uses both
  sides of the page sheet. This module provides no ability to specify whether a
  document is duplex printed, but the concept of left and right pages is based on
  the assumption that the document is duplex printed, regardless of whether or
  not it actually is.</dd>

  <dt id="binding-edge">Binding Edge</dt>
  <dd>The binding edge is the edge of the page box that is toward the binding if the
  material is bound. The binding edge often has a larger margin than the opposite
  edge to provide for the space used by the binding. The binding edge can be any
  of the four edges. However, page sheets are customarily bound so that the
  binding edge of page boxes with portrait orientation is vertical. This module
  provides no method to specify the binding edge. In duplex printing, the binding
  edge is on opposite sides of the page box for the left and right pages.</dd>

  <dt id="facing-pages">Facing Pages</dt>
  <dd>Facing pages are two sequential pages such that when the document is duplex
  printed they are on separate sheets of paper. Typically, the earlier page will
  be the back side of one sheet and the later page will be the front side of
  another. They are usually laid out so that the binding edges of facing pages
  are vertical and adjacent when the pages are placed in their normal reading
  orientation.</dd>

  <dt id="left-page">Left Page</dt>
  <dd>A page that would be on the left if it is part of a pair of facing pages as
  typically laid out. Page layouts for documents using a left-to-right page
  progression have the earlier of the facing pages on the left. Rules specific to
  the left page can be specified using the <span class="css">':left'</span> page
  selector.</dd>

  <dt id="right-page">Right Page</dt>
  <dd>A page that would be on the right if it is part of a pair of facing pages as
  typically laid out. Page layouts for documents using a right-to-left page
  progression have the earlier of the facing pages on the right. Rules specific
  to the right page can be specified using the <span class="css">':right'</span>
  page selector.</dd>
</dl>


<h2 id="page-box-page-rule">The Page Model</h2>

<p>In the paged media formatting model, the document is transferred into one
or more page boxes. The <dfn id="page-box">page box</dfn> is a specialized CSS
box that maps to a rectangular print media surface, such as a page of paper.
It is roughly analogous to the <a href="/TR/CSS21/visuren.html#viewport">viewport</a>.
<img src="PageBox.png" style="float: right;" alt="" height="266" width="267">

<p>As with other CSS <a href="/TR/CSS21/box.html">boxes</a>, a page box
consists of margin, border, padding, and content areas. The content and
margin areas of a page box have special functions:</p>

<ul>
  <li>The content area of a page box is called the <dfn id="page-area">page
  area</dfn>. The content of the document is flowed into one or more page boxes.
  The page area acts as a container for all the boxes generated by the root
  element and its descendants that are laid out within a given page box. The
  edges of the page area on the first page establish the rectangle that is the
  initial <a href="/TR/CSS21/visudet.html#containing-block-details">containing block</a>
  of the document.</li>
  <li>The margin area of a page box is divided into 16 <dfn>margin boxes</dfn>.
  Each margin box has its own margin, border, padding and content areas. Margin
  boxes are typically used to display running headers and footers.</li>
</ul>

<p>The properties of a <dfn>page box</dfn> are determined by properties
<a href="/TR/CSS21/syndata.html#declaration">declared</a> within the
<dfn><a href="#page-context">page context</a></dfn>, which is the
<a href="/TR/CSS21/syndata.html#x14">declaration block</a> of the
<code>@page</code> rule.

<p>Declarations in the page context can affect the page box and/or inherit
to the margin boxes, but they do not apply to or inherit into the
document's root element or other content.</p>

<h3 id="content-outside-box">Content outside the page box</h3>

<p>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' can 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>

<p>A specification for the exact formatting of such elements lies outside the
scope of this document. However, it is recommended that authors and user agents
observe the following general principles concerning content outside the page
box:</p>

<ul>
  <li><p>Content should be allowed slightly beyond the page box to allow pages
  to "bleed".
  <li><p>User agents <em class="RFC2119">SHOULD</em> avoid generating a large
  number of content-empty pages to honor the positioning of elements (e.g.,
  printing 100 blank pages is probably neither the author's nor the user's
  intent).
  A <dfn id="content-empty">Content-empty page</dfn> is a page box whose page
  area contains no printable content other than backgrounds and/or borders. A
  page box whose page area contains generated content, or content whose
  visibility is 'hidden', or invisible content such as a zero-width space is
  not a content-empty page. On the other hand, a page containing only a
  background and/or borders and/or margin-box content <em>is</em> a
  content-empty page.
  <p class="note">Note, however, that generating a small number of empty page
  boxes is sometimes necessary to honor the <span class="css">'left'</span> and
  <span class="css">'right'</span> values for <span class="property">'page-break-before'</span>
  and <span class="property">'page-break-after'</span>.</li>

  <li><p>Authors <em class="RFC2119">SHOULD NOT</em> position elements in
  inconvenient locations just to avoid rendering them. Instead:
  <ul>
    <li>To suppress box generation entirely, set the <span class="property">'display'</span> property to <span class="css">'none'</span>.</li>
    <li>To make a box invisible, set the <span class="property">'visibility'</span>
    property.</li>
    </ul></li>
    <li><p>This specification does not define how boxes positioned outside the page
    box are handled. Possibilities include discarding them or creating page boxes
    for them at the end of the document.</li>
</ul>

<h3 id="painting">Page Backgrounds and Painting Order</h3>

<p>When drawing a page of content, the page background and borders are painted
first (underneath). Margin-boxes are painted over (on top of) the page box.
The root element then paints the canvas and the document contents within the
page padding box.</p>

<p>The exact painting order of margin boxes is not specified, however it is
<em class="RFC2119">recommended</em> that when margin boxes overlap, paint
order should place center/middle margin boxes on top of corner margin boxes,
which are in turn painted on top of other boxes. More precisely, in terms of
the algorithm in <a href="http://www.w3.org/TR/CSS21/zindex.html">CSS2.1
Appendix E</a> the exact "tree order" of margin boxes is not defined, but it
is recommended that center/middle boxes be after corner boxes, which should
themselves be after other boxes.</p>

<p>The UA may support the <code>z-index</code> property for margin boxes. In
this case the root element, together with the canvas background and all of
the document contents, are treated as a single element with a <code>z-index</code>
value of '0': the margin boxes never interleave with parts of the document
content, they may only paint in front of or behind the document content and
its canvas. The page box itself generates a new stacking context and is treated
as the parent of all the margin boxes as well as the document content. In
other words, nothing ever paints behind the page box backgrounds or borders.
Since the <code>position</code> property does not apply to margin boxes,
<code>z-index</code> always affects margin boxes as if they were positioned
elements regardless of the <code>position</code> property's value.
<span class="issue">Mark this at-risk.</span></p>

<h3 id="progression">Page Progression</h3>

<p>CSS distinguishes between left pages and right pages on all documents,
whether they are printed duplex or not. Each left page is followed by a
right page and vice versa. Left and right pages can be styled differently
with the <a href="#left-right-first"><code>:left</code> and <code>:right</code>
pseudo-classes</a>.

<p>Whether the first page of a document is a left page or a right page
depends on the page progression of the document. The <dfn>page progression</dfn>
is the direction in which the printed pages of a document would be sequenced
when laid out side-to-side. For example, English and horizontally-set Japanese
typically progress from left to right, whereas Arabic and vertically-set
Japanese pages typically progress from right to left. In documents with with
a left-to-right page progression the first page of the document is a right
page, and vice versa.</p>

<p>The page progression direction is determined as follows:</p>

<ul>
  <li>If text is laid out in horizontal lines, the page progression is the
  same as the inline progression.</li>
  <li>If text is laid out in vertical lines, the page progression is the
  same as the block progression.</li>
</ul>

<p>If the UA supports the 'direction' and 'block-progression' properties
from the CSS 3 Text Layout Module [[CSS3TEXTLAYOUT]], it must determine
whether the first page is a left or right page from the values of those
properties on the root element.</p>

<p>To explicitly force a document to begin printing on a left or right page,
authors can <a href="#page-break-before">insert a page break before</a> the
first generated box. The UA must suppress the first (empty) page(s) in this
case (and the <code>:first</code> selector applies to the first printed
page).</p>

<h2 id="page-selector-and-context">Page Selectors and the Page Context</h2>

<h3 id="at-page-rule">The @page Rule</h3>

<p>Authors can specify various aspects of a page box, such as its dimensions,
orientation, and margins, within an <span class="css">@page</span> rule. An
<span class="css">@page</span> rule consists of the keyword <span class="css">'@page'</span>, an <em class="RFC2119">OPTIONAL</em> page name followed
with no intervening space by an <em class="RFC2119">OPTIONAL</em> page
pseudo-class, and a block of declarations (said to be in the <dfn id="page-context">page context</dfn>).
<a href="#margin-at-rules">Margin at-rules</a> may be interleaved with the
declarations in the page context.

<p>The <em class="RFC2119">OPTIONAL</em> page name and <em class="RFC2119">OPTIONAL</em> page pseudo-class constitute the <dfn id="page-selector">page selector</dfn>. The page selector specifies for which
pages the declarations apply. In CSS3, page selectors can designate the first page of a document, all left pages, all
right pages, or <a href="#using-named-pages">pages with specific names</a>.
Multiple selectors may be combined with a comma (which may be preceded and/or
followed by white space); in this case the ''@page'' rule applies to pages
that match any of the page selectors. (Note: this feature is at-risk.)
If no page selector is given, then the ''@page'' rule applies to all pages.</p>

<p>Properties declared within the page context apply to the page box.</p>

<p>If an error is encountered during the processing of a declaration block within
a page or a margin context, the <a href="/TR/CSS21/syndata.html#parsing-errors">Rules for handling parsing errors</a>
apply; that is, valid declarations within the block are applied.</p>

<h3 id="left-right-first">Page pseudo-classes: :left, :right, and :first</h3>

<p>When printing double-sided documents, left and right pages are often formatted
differently. This can be expressed through CSS pseudo-classes defined in the
<a href="#page-context">page context</a>.</p>

<p>All pages are automatically classified by user agents as either left pages or
right pages. The <span class="css">':left'</span> and <span class="css">':right'</span>
page pseudo-classes can be used to selectively apply rules to only the left or right
pages, respectively.</p>

<div class="example">
The following example creates left and right binding edges using these pseudo-classes:
<pre>
@page :left {
margin-left: 3cm;
margin-right: 4cm;
}

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

<p>If different declarations have been given for left and right pages, the user
agent <em class="RFC2119">MUST</em> honor these declarations even if the user
agent does not transfer the page boxes to left and right sheets (i.e., a
printer that only prints on one side of the medium must nevertheless produce
correctly formatted output).</p>

<p>Authors can also specify style for the first page of a document with the
<span class="css">':first'</span> pseudo-class. Such style rules are applied only
to the first printed page of a document.</p>

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

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

<div class="example">
<pre>
html {page-break-before: always;}
</pre>

<p>For an XHTML document with a left-to-right page progression, the above style
rule will cause the first page of the document to print on a ':right' page</p>
</div>
<div class="note">

<p><em><strong>Note.</strong> Adding declarations to the <span class="css">':left'</span> or <span class="css">':right'</span> pseudo-class does not
necessarily influence whether the document comes out of the printer double- or
single-sided (which is outside the scope of this specification).</em></p>
</div>
<div class="note">

<p><em><strong>Note.</strong> Future versions of CSS may include other page
pseudo-classes.</em></p>
</div>

<h3 id="syntax-page-selector">@page rule grammar</h3>

<p>The syntax for the @page rule is a specialization of the generic at-rule
defined by CSS 2.1. This grammar extends the at-rule syntax to allow @page rules
nested inside @media rules. User agents <em class="RFC2119">MUST</em> adhere
to the following grammar:</p>

<p>See [[!CSS21]], Section 4.1.1 and Appendix G for the expansion of missing
productions:</p>
<p id="specializatons-of-ATKEYWORD">
All new lexical tokens are specializations of the ATKEYWORD lexical token:</p>
<pre class="lexical">
PAGE_SYM              ::= "@page"
TOPLEFTCORNER_SYM     ::= "@top-left-corner"
TOPLEFT_SYM           ::= "@top-left"
TOPCENTER_SYM         ::= "@top-center"
TOPRIGHT_SYM          ::= "@top-right"
TOPRIGHTCORNER_SYM    ::= "@top-right-corner"
BOTTOMLEFTCORNER_SYM  ::= "@bottom-left-corner"
BOTTOMLEFT_SYM        ::= "@bottom-left"
BOTTOMCENTER_SYM      ::= "@bottom-center"
BOTTOMRIGHT_SYM       ::= "@bottom-right"
BOTTOMRIGHTCORNER_SYM ::= "@bottom-right-corner"
LEFTTOP_SYM           ::= "@left-top"
LEFTMIDDLE_SYM        ::= "@left-middle"
LEFTBOTTOM_SYM        ::= "@left-bottom"
RIGHTTOP_SYM          ::= "@right-top"
RIGHTMIDDLE_SYM       ::= "@right-middle"
RIGHTBOTTOM_SYM       ::= "@right-bottom"

<span id="syntax-prod-media">media</span> :
     MEDIA_SYM S* medium [ COMMA S* medium ]* LBRACE S* [ page | ruleset ]* '}' S*
     ;

<span id="syntax-prod-page">page</span> :
     PAGE_SYM S* IDENT? S* pseudo_page? S*
     '{' S* [ margin_box | ruleset ]? [ ';' S* [ margin_box | ruleset ]? ]* '}' S*
     ;
<span class="issue">Space should not be allowed between name and pseudo.</span>
<span id="syntax-prod-pseudo-page">pseudo_page</span> :
     ':' [ "left" | "right" | "first" ]
     ;

<span id="syntax-prod-margin">margin_box</span> :
     margin_sym S* '{' ruleset* '}' S*
     ;

<span id="syntax-prod-margin-sym">margin_sym</span> :
     TOPLEFTCORNER_SYM |
     TOPLEFT_SYM |
     TOPCENTER_SYM |
     TOPRIGHT_SYM |
     TOPRIGHTCORNER_SYM |
     BOTTOMLEFTCORNER_SYM |
     BOTTOMLEFT_SYM |
     BOTTOMCENTER_SYM |
     BOTTOMRIGHT_SYM |
     BOTTOMRIGHTCORNER_SYM |
     LEFTTOP_SYM |
     LEFTMIDDLE_SYM |
     LEFTBOTTOM_SYM |
     RIGHTTOP_SYM |
     RIGHTMIDDLE_SYM |
     RIGHTBOTTOM_SYM
     ;
</pre>

<p id="page-selector-syntax-restrict">
The value 'auto' is not a valid page name and must be treated as matching
nothing.

<div class="example">

<p>The following are examples of page selectors (declaration block intentionally
left blank)</p>
<pre>
@page { ... }
@page :left { ... }
@page :right { ... }
@page LandscapeTable { ... }
@page CompanyLetterHead:first { ... } /*  identifier and pseudo page. */
@page:first { ... };
</pre>

<p>The following are examples of margin boxes where the declaration blocks are
intentionally left blank.</p>
<pre>
@page {
 @top-left { ... /* document name */ }
 @bottom-center { ... /* page number */}
}
@page :left { @left-middle { ... /* page number in left margin */ }}
@page :right{ @right-middle { ... /* page number in right margins of right pages */}}

@page :left { @bottom-left-corner { ... /* left page numbers */ }}
@page :right { @bottom-right-corner { ... /* right page numbers */ }}
@page :first { @bottom-left-corner { ... /* empty footer on 1st page */ }
             @bottom-right-corner { ... /* empty footer */ } }
</pre>
</div>

<h3 id="cascading-and-page-context">Cascading in the page context</h3>

<p>Declarations in page and margin contexts <a href="/TR/CSS21/cascade.html">cascade</a> just like declarations in <a href="/TR/CSS21/syndata.html#rule-sets">rule sets</a>.</p>

<p>The specificity of page selectors is computed in a manner analogous to the
computations defined in the <a href="/TR/CSS21/selector.html">Selectors</a>
module:</p>

<ul>
  <li>if the page selector has a named page, f=1; else f=0</li>
  <li>if the page selector has a ':first' pseudo-class, g=1; else g=0</li>
  <li>if the page selector has a ':left' or ':right' pseudo-class, h=1; else h=0</li>
</ul>

<p>Concatenating the three numbers f-g-h gives the specificity.</p>

<p>Properties that are not explicitly set within the page or margin context take
their initial values and do not inherit from any element.</p>

<div class="example">

<p>Some page specificity calculation examples follow:</p>
<pre>
      @page { } /* f=0 g=0 h=0 -&gt; specificity = 000 */
      @page :left { } /* f=0 g=0 h=1 -&gt; specificity = 001 */
      @page :first { } /* f=0 g=1 h=0 -&gt; specificity = 010 */
      @page artsy { } /* f=1 g=0 h=0 -&gt; specificity = 100 */
      @page artsy:left { } /* f=1 g=0 h=1 -&gt; specificity = 101 */
      @page artsy:first { } /* f=1 g=1 h=0 -&gt; specificity = 110 */
</pre>
</div>

<div class="example">

<p>Consider the following usage example:</p>
<pre>
@page {
margin-left: 3cm;
}

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

<p>Due to the higher specificity of the pseudo-class selector, the left margin on
left pages will be 4cm and all other pages
(the right-facing pages) will have a left margin of 3cm.</p>
</div>

<div class="example">

<p>In this example, the higher specificity of the green rules wins over the red
rule. Therefore the first page will have blue text in the top-left margin box
and green text in the top-right margin box, while subsequent pages will have
red text in the margin boxes.</p>
<pre>
@page :first {
color: green;

@top-left {
  content: "foo";
  color: blue;
}
@top-right {
  content: "bar";
}
}

@page { color: red;
@top-center {
  content: "Page " counter(page);
  }
}
</pre>
</div>

<div class="example">

<p>Page contexts cascade, so the following stylesheet would style pages with 25
millimeter margins and 14 point type in the margin boxes:</p>
<pre>
@page { margin: 25mm;}
@page { font-size: 14pt;}
</pre>
</div>

<h2 id="margin-boxes">Margin Boxes</h2>

<p>Margin boxes are boxes within the page margin that, like pseudo-elements,
can contain generated content.</p>

<p>Margin boxes can be used to create page headers and footers, which are portions
of the page set aside for supplementary information such as the page number or
document title.</p>

<div class="example">
<p>Typically, a <dfn>page header</dfn> is located at the top of the page in
documents with a predominately horizontal writing direction and on the side
opposite the <a href="#binding-edge">binding edge</a> for documents with a
predominately vertical writing direction. One possible design of page headers
for horizontally written documents uses the <span class="css">'top-left-corner'</span>, <span class="css">'top-left'</span>,
<span class="css">'top-center'</span>, <span class="css">'top-right'</span> and
<span class="css">'top-right-corner'</span> margin boxes. Another design, for
vertically written documents, could use the <span class="css">'right-top'</span>, <span class="css">'right-middle'</span>, and
<span class="css">'right-bottom'</span> margin boxes for <a href="#right-page">right facing pages</a> and <span class="css">'left-top'</span>,
<span class="css">'left-middle'</span>, and <span class="css">'left-bottom'</span> for <a href="#left-page">left facing pages</a>.</p>

<p>The <dfn>page footer</dfn> is typically at the opposite end of the page from
the page header. For example, the design of a horizontally written document with
a page header at the top of the page could use the <span class="css">'bottom-left-corner'</span>, <span class="css">'bottom-left'</span>,
<span class="css">'bottom-center'</span>, <span class="css">'bottom-right'</span> and <span class="css">'bottom-right-corner'</span>
margin boxes as the page footer. The design of a vertically written document
could use the margin boxes of the binding edge of the page for the page footer.</p>
</div>

<p>Margin boxes are oriented with respect to the content and are independent of
page orientation, for example the top margin boxes are above the page area in
both portrait and landscape orientation. The various margin boxes are defined
and illustrated in the diagram below:

  <table id="margin-box-def" class="data" summary="defintion of each of the margin boxes">
    <caption>Table 1 Margin Box Definitions</caption>
    <thead>
      <tr>
        <th>Box</th>
        <th>Description</th>
        <th>Placement</th>
      </tr>
    </thead>
    <tbody>
      <tr id="top-margin-boxes-def">
        <th id="top-left-corner-box-def">top-left-corner</th>
        <td>a fixed-size box defined by the intersection of the top and left margins of the
        page box</td>
        <td><img src="TopLeftCornerBox.png" alt="the top left corner box with margin, border, and padding, nested within intersection of the page's top and left margins"
        height="47" width="181"></td>
      </tr>
      <tr id="top-left-box-def">
        <th>top-left</th>
        <td>a variable-width box filling the top page margin between the top-left-corner
        and top-center margin boxes</td>
        <td><img src="TopLeftMarginBox.png" alt="the top left box with margin, border, and padding, nested in the page's top margin next to the top left corner box"
        height="47" width="181"></td>
      </tr>
      <tr id="top-center-box-def">
        <th>top-center</th>
        <td>a variable-width box centered horizontally between the page's left and right
        border edges and filling the page top margin between the top-left and top-right
        margin boxes</td>
        <td><img src="TopCenterMarginBox.png" alt="the top center box with margin, border, and padding, centered within the page's top margin"
        height="47" width="181"></td>
      </tr>
      <tr id="top-right-box-def">
        <th>top-right</th>
        <td>a variable-width box filling the top page margin between the top-center and
        top-right-corner margin boxes</td>
        <td><img src="TopRightMarginBox.png" alt="the top right box with margin, border, and padding, nested within the page's top margin"
        height="47" width="181"></td>
      </tr>
      <tr>
        <th id="top-right-corner-box-def">top-right-corner</th>
        <td>a fixed-size box defined by the intersection of the top and right margins of
        the page box</td>
        <td><img src="TopRightCornerMarginBox.png" alt="the top right corner box with margin, border, and padding, nested within the intersection of the page's top and right margin"
        height="47" width="181"></td>
      </tr>
      <tr id="left-margin-boxes-def">
        <th id="left-top-box-def">left-top</th>
        <td>a variable-height box filling the left page margin between the top-left-corner
        and left-middle margin boxes</td>
        <td rowspan="3"><img src="LeftMarginBoxes.png" alt="left-top, left-middle, and left-bottom margin boxes in the page box's left margin"
        height="226" width="181"></td>
      </tr>
      <tr id="left-middle-box-def">
        <th>left-middle</th>
        <td>a variable-height box centered vertically between the page's top and bottom
        border edges and filling the left page margin between the left-top and
        left-bottom margin boxes</td>
      </tr>
      <tr id="left-bottom-box-def">
        <th>left-bottom</th>
        <td>a variable-height box filling the left page margin between the left-middle and
        bottom-left-corner margin boxes</td>
      </tr>
      <tr id="right-margin-boxes-def">
        <th id="right-top-box-def">right-top</th>
        <td>a variable-height box filling the right page margin between the
        top-right-corner and right-middle margin boxes</td>
        <td rowspan="3"><img src="RightMarginBoxes.png" alt="right-top, right-middle, and right-bottom margin boxes in the page box's right margin"
        height="226" width="181"></td>
      </tr>
      <tr id="right-middle-box-def">
        <th>right-middle</th>
        <td>a variable-height box centered vertically between the page's top and bottom
        border edges and filling the right page margin between the right-top and
        right-bottom margin boxes</td>
      </tr>
      <tr id="right-bottom-box-def">
        <th>right-bottom</th>
        <td>a variable-height box filling the right page margin between the right-middle
        and bottom-right-corner margin boxes</td>
      </tr>
      <tr id="bottom-margin-boxes-def">
        <th id="bottom-left-corner-box-def">bottom-left-corner</th>
        <td>a fixed-size box defined by the intersection of the bottom and left margins of
        the page box</td>
        <td><img src="BottomLeftCornerBox.png" alt="bottom left corner box with margin, border, and padding, nested within the page margin at the intersection of the left and bottom page margins"
        height="48" width="181"></td>
      </tr>
      <tr id="bottom-left-box-def">
        <th>bottom-left</th>
        <td>a variable-width box filling the bottom page margin between the
        bottom-left-corner and bottom-center margin boxes</td>
        <td><img src="BottomLeftMarginBox.png" alt="bottom left margin box with margin, border, and padding, nested within the page's bottom margin next to the bottom-left-corner box"
        height="48" width="181"></td>
      </tr>
      <tr id="bottom-center-box-def">
        <th>bottom-center</th>
        <td>a variable-width box centered horizontally between the page's left and right
        border edges and filling the bottom page margin between the bottom-left and
        bottom-right margin boxes</td>
        <td style="vertical-align: middle;"><img src="BottomCenterMarginBox.png" alt="bottom center box with margin, border, and padding, nested within the page's bottom margin and centered on the page"
        height="48" width="181"></td>
      </tr>
      <tr id="bottom-right-box-def">
        <th>bottom-right</th>
        <td>a variable-width box filling the bottom page margin between the bottom-center
        and bottom-right-corner margin boxes</td>
        <td><img src="BottomRightMarginBox.png" alt="bottom right margin box with margin, border, and padding, nested within the page's bottom margin and next to the bottom-right-corner box"
        height="48" width="181"></td>
      </tr>
      <tr id="bottom-right-corner-box-def">
        <th>bottom-right-corner</th>
        <td>a fixed-size box defined by the intersection of the bottom and right margins of
        the page box</td>
        <td><img src="BottomRightCornerBox.png" alt="bottom right corner box with margin, border, and padding, nested within the page margin at the intersection of the right and bottom page margins"
        height="48" width="181"></td>
      </tr>
    </tbody>
  </table>

<h3 id="margin-at-rules">At-rules for margin boxes</h3>

<p>Margin boxes are created by <a href="#margin-at-rules">margin at-rules</a>
inside the <a href="#page-context">page context</a>.
These rules should come after any declarations in the page context as legacy
clients may not handle declarations after margin at-rules correctly.</p>

<p>A <dfn id="margin-at-rule">margin at-rule</dfn> consists of an <a href="#specializatons-of-ATKEYWORD">ATKEYWORD</a> that identifies the margin box
(e.g. <span class="css">'@top-left'</span>) and a block of declarations (said
to be in the <dfn id="margin-context">margin context</dfn>).</p>

<div class="example">

<p>The following style sheet establishes a page header containing the title
("Hamlet") on the left side and the page number, preceded by "Page ", on the
right side:</p>
<pre>
@page {
  size: 8.5in 11in;
  margin: 10%;

  @top-left {
    content: "Hamlet";
  }
  @top-right {
    content: "Page " counter(page);
  }
}
</pre>
</div>


<h3 id="populating-margin-boxes">Populating margin boxes</h3>

<p>A margin box is instantiated if and only if the computed value of its
'content' property does not match that of its initial value.

<div class="example">
<p>The following style sheet creates a green box in each corner of the page
except the bottom-left corner.</p>
<pre>
  @page {
    @top-left-corner { content: " "; border: solid green; }
    @top-right-corner { content: url(foo.png); border: solid green; }
    @bottom-right-corner { content: counter(page); border: solid green; }
    @bottom-left-corner { content: normal; border: solid green; }
  }
</pre>
</div>

<h3 id="margin-box-dimensions">Computing Margin Box Dimensions</h3>

<p>The width and height of each margin box is determined by the rules
below. These rules define the equivalent of CSS2.1 Sections 10.3 and
10.6 for margin boxes.</p>

<p>The rules for applying 'min-height', 'max-height', 'min-width', and
'max-width' [[!CSS21]] do apply to margin boxes and may imply a recalculation
of the width, height, and/or margins if the dimensions resulting from the
specified 'width' or 'height' violate their constraints. If the UA does not
support the 'min-height' or 'min-width' properties then it must behave as
if 'min-height' and 'min-width' were always zero.

<h4 id="max-margin-dimension">Margin Box Layout Terminology</h4>

<p>In addition to the box model definitions in CSS2.1 [[!CSS21]], the following
terms are defined for use in the subsequent margin box calculations:</p>

<dl>

<dt id="MaxBoxWidth">max box width</dt>
<dd>the sum of the page's left border width, left padding,
<a href="#page-box">page area</a> width, right padding, and right border width.
In other words, it is the distance between the <a href="#page-box">page
box</a>'s left border edge and right border edge</a>. This quantity is used
when calculating dimensions of the top and bottom margin boxes.</dd>

<dt id="MaxBoxHeight">max box height</dt>
<dd>the sum of the page's top border width, top padding,
<a href="#page-box">page area</a> height, bottom padding, and bottom border
width. In other words, it is the distance between the <a href="#page-box">page
box</a>'s top border edge and bottom border edge. This quantity is used when
calculating dimensions of the left and right margin boxes.</dd>

<dt>outer width</dt>
<dd>the sum of a margin box's left and right margins, left and right border
widths, left and right padding, and content-box width.</dd>

<dt>outer height</dt>
<dd>the sum of a margin box's top and bottom margins, top and bottom border
widths, top and bottom padding, and content-box height.</dd>
</dl>

<p>The <dfn>containing block</dfn> for a corner margin box is the rectangle
defined by the intersection of the two page margins meeting at that corner.</p>

<p>For all other margin boxes, the <dfn>containing block</dfn> is the rectangle
formed by the encapsulating page margin minus the containing blocks of the
adjacent corners' margin boxes. This means that the size of this containing
block is given in one dimension by the used page margin and in the other
dimension by the <a href="#MaxBoxWidth">max box width</a> (for top and bottom
margin boxes) or <a href="#MaxBoxHeight">max box height</a> (for left and right
margin boxes).</p>

<h4 id="margin-dimension">Margin Box Variable Dimension Computation Rules</h4>

<p>The following rules apply to 'top-left', 'top-center' and 'top-right' margin
boxes, which are referred to as A, B, and C, respectively, in the expression
below.</p>

<ul>
<li>The UA chooses used values for each box's width, left and right margin,
  left and right border thickness, and left and right padding. It chooses them in
  such a way that the sum of the squares of the boxes' left and right margins,
  i.e. the value of:
  <div class="equation">
    margin-left<sub>A</sub>² + margin-left<sub>B</sub>² + margin-left<sub>C</sub>² + margin-right<sub>A</sub>² + margin-right<sub>B</sub>² + margin-right<sub>C</sub>²
  </div>
  is as small as possible under the constraints below.

  <ol>
    <li>The sum of the outer widths of the three boxes is equal to max box width.
      (Margin box margins do not collapse.)</li>
    <li>If the center box is not empty or if its computed width is not 'auto', then
    the outer widths of the other two boxes are equal to each other (i.e., the
    center box is centered in that case).</li>
    <li>If a box is empty and its computed width is 'auto', then the used values of
    its left and right padding width and left and right border width are all 0.