-
Notifications
You must be signed in to change notification settings - Fork 790
Expand file tree
/
Copy pathOverview.bs
More file actions
2410 lines (2029 loc) · 88.4 KB
/
Overview.bs
File metadata and controls
2410 lines (2029 loc) · 88.4 KB
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
630
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
<pre class='metadata'>
Title: CSS Paged Media Module Level 3
Shortname: css-page
Level: 3
Status: WD
Date: 2018-10-18
Remove Multiple Links: false
Work Status: Revising
Group: csswg
ED: https://drafts.csswg.org/css-page-3/
TR: https://www.w3.org/TR/css-page-3/
Previous Version: https://www.w3.org/TR/2013/WD-css3-page-20130314/
Issue Tracking: Tracker http://www.w3.org/Style/CSS/Tracker/products/13
Editor: Elika J. Etemad / fantasai, Invited Expert, formerly Mozilla, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Simon Sapin, Mozilla, formerly Kozea, http://exyr.org/about/, w3cid 58001
Ignored terms: fit, fit-position, stacking context
Link defaults: css-break (property) break-after, css2 (property) display, css2 (property) min-height, css2 (property) max-height, css2 (property) min-width, css2 (property) max-width, css2 (property) margin, css2 (property) counter-increment, css2 (property) counter-reset
Abstract: This CSS module specifies how pages are generated and laid out to hold fragmented content in a paged presentation. It adds functionality for controlling page margins, page size and orientation, and headers and footers, and extends generated content to enable page numbering and running headers / footers. The process of paginating a flow into such generated pages is covered in [[!CSS3-BREAK]].
</pre>
<style type="text/css">
#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;
}
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>
<h2 id="intro">
Introduction</h2>
Paged media (e.g., paper, transparencies, photo album pages, pages
displayed on computer screens as printed output simulations) differ from
<a href="https://www.w3.org/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:
<ul>
<li><a href="#page-breaks">page breaks</a> are created and avoided;
<li>the page properties such as size, orientation, margins, border, and
padding are specified;
<li>headers and footers are established within the page margins;
<li>content such as page counters are placed in the headers and footers; and
<li>orphans and widows can be controlled.
</ul>
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.
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.
All properties defined in this specification also accept the
<a href="https://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="page-terms">
Page Terminology</h2>
The following terminology and accompanying diagrams help to describe the
page model:
<dl>
<dt><dfn export>Page sheet</dfn>
<dd>
<img src="images/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.
<dt><dfn export lt="printable area">Printable and non-printable areas</dfn>
<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
may 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
[[#renderingpages]] and [[#content-outside-box]].
<dt><dfn export>Page Orientation</dfn>
<dd>
The page orientation is defined by comparing the length of the edges of a
<a>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''.
<dt><dfn export lt="portrait|portrait orientation">Portrait Orientation</dfn>
<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.
<dt><dfn export lt="landscape|landscape orientation">Landscape Orientation</dfn>
<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.
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.
<dt><dfn export>Duplex Printing</dfn>
<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.
<dt><dfn export>Binding Edge</dfn>
<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.
<dt><dfn export>Facing Pages</dfn>
<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.
<dt><dfn export>Left Page</dfn>
<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 '':left'' <a>page selector</a>.
<dt><dfn export>Right Page</dfn>
<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 '':right'' <a>page selector</a>.
</dl>
<h2 id="page-model">The Page Model</h2>
In the paged media formatting model, the document is transferred into one
or more page boxes. The <dfn export>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="https://www.w3.org/TR/CSS21/visuren.html#viewport">viewport</a>.
<img src="images/PageBox.png" style="float: right;" alt="" height="266" width="267">
As with other CSS <a href="https://www.w3.org/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:
Issue: In CSS 2.1, both the page box and page area are simple rectangles.
Neither is a CSS box with margins, borders, and padding.
This CSS box should be distinct from the page box and page area,
which would be its margin area and content area, respectively.
Naming ideas?
<ul>
<li>
The content area of a page box is called the <dfn export>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>containing block</a>
of the document.
<li>
The margin area of a page box is divided into
16 <dfn export>page-margin boxes</dfn>.
Each page-margin box has its own margin, border, padding and content areas.
Page-margin boxes are typically used to display running headers and footers.
</ul>
The properties of a <a>page box</a> are determined by properties
declared within the <a>page context</a>, which is the
<a href="https://www.w3.org/TR/CSS21/syndata.html#x14">declaration block</a> of the
''@page'' rule. Similarly the properties of a <a>page-margin box</a>
are determined by properties declared within its <a>margin context</a>.
Declarations in the page context can affect the page box and/or inherit
to the page-margin boxes, but they do not apply to or inherit into the
document's root element or other content.
The <a>containing block</a> of the page box is specified using the 'size'
property in the <a>page context</a>. The width and horizontal margins
of the page box are then calculated exactly as for a
<a href="https://www.w3.org/TR/CSS21/visudet.html#blockwidth">non-replaced block element in normal flow</a>. [[!CSS21]]
The height and vertical margins
of the page box are calculated analogously (instead of using the block height
formulas). In both cases if the values are over-constrained, instead of
ignoring any margins, the containing block is resized to coincide with the
margin edges of the page box.
<h3 id="painting">
Page Backgrounds and Painting Order</h3>
When drawing a page of content, the page layers are painted in the
following painting order (bottommost first):
<ol>
<li>page background
<li>document canvas
<li>page borders
<li>document contents
<li>page-margin boxes
</ol>
In the page model, the page background behaves similar to the root background:
its <a spec=css-backgrounds>background painting area</a> is the <a>bleed area</a>,
which covers the entire page box, including its margins (regardless of 'background-clip').
Page backgrounds are anchored within the page box's padding area by default
(and honor 'background-origin' if the UA supports [[!CSS3BG]]).
However if 'background-attachment' is ''background-attachment/fixed''
then the image is positioned relative to the page box including its margins
(i.e. the <a spec=css-backgrounds>background positioning area</a>
is the page's margin box).
The document canvas background is drawn as the page box's background:
by default its <a spec=css-backgrounds>background painting area</a> covers the page box's border box,
and for UAs that support [[!CSS3BG]], follows the 'background-clip' value specified on the root element.
It remains, however, positioned with respect to the root element
or page area as usual.
With respect to the page-margin boxes,
the document canvas, page borders, and all of the document contents
are treated as a single element with a <code>z-index</code> value of ''0''
that establishes a
<a>stacking context</a>
[[!CSS21]]:
the page-margin boxes never interleave with parts of the document content
or between the content and the canvas.
They may only paint in front of the document content
or behind the document canvas.
The page background is always painted underneath everything else.
The 'z-index' property applies to page-margin boxes.
Since the 'position' property does not apply to page-margin boxes,
'z-index' always affects page-margin boxes as if they were positioned elements
regardless of the 'position' property's value.
Each page-margin boxes always establishes a stacking context.
The default painting order,
or <a href="https://www.w3.org/TR/CSS21/zindex.html">CSS2.1 Appendix E</a> "tree order",
of page-margin boxes with respect to each other is as follows:
<ol>
<li>''@top-left-corner''
<li>''@top-left''
<li>''@top-center''
<li>''@top-right''
<li>''@top-right-corner''
<li>''@right-top''
<li>''@right-middle''
<li>''@right-bottom''
<li>''@bottom-right-corner''
<li>''@bottom-right''
<li>''@bottom-center''
<li>''@bottom-left''
<li>''@bottom-left-corner''
<li>''@left-bottom''
<li>''@left-middle''
<li>''@left-top''
</ol>
<p class=note>
Start with ''@top-left-corner'', then go clockwise.
This order is arbitrary but can be overridden with 'z-index'.
It only has a visible effect when page-margin boxes overlap,
which should not happen in most cases.
<h3 id="content-outside-box">Content outside the page box</h3>
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.
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:
<ul>
<li>Content should be allowed slightly beyond the page box to allow pages
to "bleed".
<li>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 export 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 ''visibility/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 page-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 forced-break values for
'page-break-before'/'break-before' and 'page-break-after'/'break-after'.
[[!CSS21]] [[!CSS3-BREAK]]
<li>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 'display' property to ''display/none''.
<li>To make a box invisible, set the <span class="property">'visibility'</span>
property.
</ul>
<li>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.
</ul>
<h3 id="progression">Page Progression</h3>
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>.
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 export>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.
The page progression direction is determined as follows:
<ul>
<li>If text is laid out in horizontal lines,
the <a>page progression</a> is the same as the <a>inline base direction</a>.
<li>If text is laid out in vertical lines,
the <a>page progression</a> is the same as the <a>block flow direction</a>.
</ul>
If the UA supports the 'direction' and 'writing-mode' properties
from the CSS 3 Writing Modes Module [[CSS3-WRITING-MODES]], it must
<a href="https://www.w3.org/TR/css3-writing-modes/#page-direction">determine</a>
the <a>page progression</a> is determed by the <a>principal writing mode</a>.
In documents with a left-to-right <a>page progression</a>
the first page of the document is a right page, and vice versa.
To explicitly force a document to begin printing on a left or right page,
authors can specify a 'break-before' value
that that propagates a page break to the root. [[!CSS3-BREAK]]
The UA must suppress the first (empty) page(s) in this case
(and the <code>:first</code> pseudo-class matches the first printed page).
<div class="example">
<pre>
html { break-before: always }
</pre>
For an HTML document with a left-to-right page progression,
the above style rule will cause the first page of the document
to print on a ':left' page
<pre>
html { break-before: left }
</pre>
For an HTML document,
the above style rule will cause the first page of the document
to print on a ':left' page,
regardless of the page progression.
</div>
<h2 id="page-selector-and-context">
Page Selectors and the Page Context</h2>
<h3 id="at-page-rule"><span id="page-box-page-rule"></spans>
The @page Rule</h3>
Authors can specify various aspects of a page box,
such as its dimensions, orientation, and margins,
within an <dfn>@page</dfn> rule.
''@page'' rules are allowed
wherever <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">rule-sets</a> are allowed.
An ''@page'' rule consists of the keyword ''@page'',
an optional comma-separated list of
<a>page selectors</a>
and a block of declarations
(said to be in the <dfn export id="page-context">page context</dfn>).
An ''@page'' rule can also contain other at-rules,
interleaved between declarations.
The current level of this specification
only allows <a>margin at-rules</a> inside ''@page''.
''@page'' rules without a selector list apply to every page.
Other ''@page'' rules apply to pages that <a>match</a>
at least one of their selectors.
Properties declared within the page context apply to the page box.
If an error is encountered during the processing of a declaration block within
a page or a margin context, the <a href="https://www.w3.org/TR/CSS21/syndata.html#parsing-errors">Rules for handling parsing errors</a>
apply; that is, valid declarations within the block are applied.
<h3 id="page-selectors">Page selectors</h3>
A <dfn export id="page-selector">page selector</dfn> is made of
either a <a>page type selector</a>
or a <a>page pseudo-class</a>,
followed by zero or more additional <a>page pseudo-classes</a>.
No whitespace is allowed between components of a selector.
The <<page-selector>> grammar
and examples can be found below.
A <a>page selector</a> is said to <dfn>match</dfn> a given page if and only if
all of its components match the page.
A <dfn export>page type selector</dfn> is
a case-sensitive <a href="https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier">CSS identifier</a> [[!CSS21]].
It <a>matches</a> pages of the <a href="#using-named-pages">named page type</a>
generated by the 'page' property.
<span id="page-selector-syntax-restrict">
A page type name of ''page/auto''
(<a href="https://www.w3.org/TR/CSS21/syndata.html#characters">ASCII case-insensitive</a>)
does not make the rule invalid,
but must never match.
</span>
A <dfn export>page pseudo-class</dfn> is <a href="https://www.w3.org/TR/CSS21/syndata.html#characters">ASCII case-insensitive</a>
and has the same syntax as <a href="https://www.w3.org/TR/selectors/#pseudo-classes">pseudo-classes</a> in regular Selectors. [[!SELECT]]
The various <a>page pseudo-classes</a> are defined below.
<h4 id="spread-pseudos"><span id="left-right-first"></span>
Spread pseudo-classes: '':left'', '':right''</h4>
When printing double-sided documents,
left and right pages are often formatted differently.
This can be expressed by using the '':left'' and '':right'' page pseudo-classes.
<p dfn-type="value" dfn-for="@page">All pages are automatically classified by user agents
as either left pages or right pages,
based on <a href="#progression">page progression</a>.
The <dfn>:left</dfn> and <dfn>:right</dfn> pseudo-classes
only <a>match</a> <a lt="left page">left</a> or <a lt="right page">right pages</a>,
respectively.
<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>
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 (i.e., a
printer that only prints on one side of the medium must nevertheless produce
correctly formatted output).
<div class="note">
<em><strong>Note.</strong>
Adding declarations to the '':left'' or '':right'' 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>
</div>
<h4 id="first-pseudo">
First-page pseudo-class: '':first''</h4>
The <dfn dfn-type="value" dfn-for="@page">:first</dfn> pseudo-class <a lt="match">matches</a>
the first printed page of a document.
<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>
<h4 id="blank-pseudo">
Blank-page pseudo-class: ''@page/:blank''</h4>
The <dfn dfn-type="value" dfn-for="@page">:blank</dfn> pseudo-class <a lt="match">matches</a>
<a lt="content-empty page">content-empty pages</a>
that appear as a result of
<a href="https://www.w3.org/TR/css3-break/#forced-breaks">forced page breaks</a>.
<div class="note">
Only the ''break-before/left'', ''break-before/right'', ''break-before/recto'' and ''break-before/verso'' values
of the 'break-before' and 'break-after' properties
can generate pages that match ''@page/:blank''.
</div>
<div class="example">
In this example, forced page break may occur before <code>h1</code> elements.
<pre>
h1 { break-before: left }
@page :blank {
@top-center { content: "This page is intentionally left blank" }
}
</pre>
</div>
A page matched by ''@page/:blank'' can also be matched
by other page pseudo-classes.
<div class="example">
If headers have been specified on all right pages, a blank right
page will be matched by both <code>:blank</code>
and <code>:right</code>. Therefore, margin boxes set on right pages
will have to be removed unless they are wanted on blank pages. Here is
an example where the top center header is removed from blank pages,
while the page number remains:
<pre>
h1 { break-before: left }
@page :blank {
@top-center { content: none }
}
@page :right {
@top-center { content: "Preliminary edition" }
@bottom-center { content: counter(page) }
}
</pre>
Due to the higher <a>specificity</a> of <code>:blank</code>
over <code>:right</code>, the top center header is removed even
if <code>content: none</code> comes before <code>content: "Preliminary
edition"</code>.
</div>
<div class="note">
<em><strong>Note.</strong> Future versions of CSS may include other page
pseudo-classes.</em>
</div>
<h3 id="syntax-page-selector">@page rule grammar</h3>
''@page'' rules are [=CSS/parsed=] according to the following grammar,
plus the additional rules noted below:
<pre class=prod>
@page = @page <<page-selector-list>>? { <<declaration-list>> }
<dfn><<page-selector-list>></dfn> = <<page-selector>>#
<dfn><<page-selector>></dfn> = [ <<ident-token>>? <<pseudo-page>>* ]!
<dfn><<pseudo-page>></dfn> = ':' [ left | right | first | blank ]
/* Margin rules */
<dfn>@top-left-corner</dfn> = @top-left-corner { <<declaration-list>> };
<dfn>@top-left</dfn> = @top-left { <<declaration-list>> };
<dfn>@top-center</dfn> = @top-center { <<declaration-list>> };
<dfn>@top-right</dfn> = @top-right { <<declaration-list>> };
<dfn>@top-right-corner</dfn> = @top-right-corner { <<declaration-list>> };
<dfn>@bottom-left-corner</dfn> = @bottom-left-corner { <<declaration-list>> };
<dfn>@bottom-left</dfn> = @bottom-left { <<declaration-list>> };
<dfn>@bottom-center</dfn> = @bottom-center { <<declaration-list>> };
<dfn>@bottom-right</dfn> = @bottom-right { <<declaration-list>> };
<dfn>@bottom-right-corner</dfn> = @bottom-right-corner { <<declaration-list>> };
<dfn>@left-top</dfn> = @left-top { <<declaration-list>> };
<dfn>@left-middle</dfn> = @left-middle { <<declaration-list>> };
<dfn>@left-bottom</dfn> = @left-bottom { <<declaration-list>> };
<dfn>@right-top</dfn> = @right-top { <<declaration-list>> };
<dfn>@right-middle</dfn> = @right-middle { <<declaration-list>> };
<dfn>@right-bottom</dfn> = @right-bottom { <<declaration-list>> };
</pre>
In addition, the following rules apply:
* No whitespace is allowed between the productions in <<page-selector>> or <<pseudo-page>>
(similar to the rule for <<compound-selector>>).
* The ''@page'' rule can only contain <a>page properties</a> and <a>margin at-rules</a>.
* The <a>margin at-rules</a> can only contain <a>page-margin properties</a>.
<div class="example">
The following are examples of page selectors (declaration block intentionally
left blank)
<pre>
@page { ... }
@page :left { ... }
@page :right { ... }
@page LandscapeTable { ... }
@page CompanyLetterHead:first { ... } /* identifier and pseudo page. */
@page:first { ... }
@page toc, index { ... }
@page :blank:first { ... }
</pre>
The following are examples of page-margin boxes
where the declaration blocks are intentionally left blank.
<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>
Declarations in page and margin contexts <a href="https://www.w3.org/TR/CSS21/cascade.html">cascade</a> just like declarations in style rule for elements.
The <dfn>specificity</dfn> of page a selector is computed in a manner
analogous to the computations defined in
the <a href="https://www.w3.org/TR/CSS21/selector.html">Selectors</a> module:
<ul>
<li>Count the number of page type names (= <var>f</var>)
<p class="note">
Given the syntax of page selectors, <var>f</var> can only ever be 0 or 1.
<li>Count the number of ':first' or ':blank' pseudo-classes (= <var>g</var>)
<li>Count the number of ':left' or ':right' pseudo-classes (= <var>h</var>)
</ul>
<p class="note">
Note: Repeated occurrences of the same pseudo-classes are allowed
and do increase specificity.
Due to storage limitations,
implementations may have limitations on
the size of <var>f</var>, <var>g</var>, or <var>h</var>.
If so, values higher than the limit must be clamped to that limit,
and not overflow.
Specificities are compared by comparing the three components in order
(<var>f</var>, <var>g</var>, <var>h</var>):
the specificity with a larger <var>f</var> value is more specific;
if the two <var>f</var> values are tied,
then the two <var>g</var> values are compared, etc.
If all the values are tied, the two specificities are equal.
<div class="example">
Some page specificity calculation examples follow:
<pre>
@page { } /* specificity = (0,0,0) */
@page :left { } /* specificity = (0,0,1) */
@page :first { } /* specificity = (0,1,0) */
@page :blank:left { } /* specificity = (0,1,1) */
@page artsy { } /* specificity = (1,0,0) */
@page artsy:left { } /* specificity = (1,0,1) */
@page artsy:first { } /* specificity = (1,1,0) */
</pre>
</div>
<div class="example">
Consider the following usage example:
<pre>
@page :left {
margin-left: 4cm;
}
@page {
margin-left: 3cm;
}
</pre>
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.
</div>
<div class="example">
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 page-margin box
and green text in the top-right page-margin box,
while subsequent pages will have red text in the page-margin boxes.
<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">
Page contexts cascade, so the following stylesheet would style pages with 25
millimeter margins and 14 point type in the page-margin boxes:
<pre>
@page { margin: 25mm;}
@page { font-size: 14pt;}
</pre>
</div>
<h2 id="margin-boxes">Page-Margin Boxes</h2>
Page-margin boxes are boxes within the page margin that,
like pseudo-elements, can contain generated content.
Page-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.
<div class="example">
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>binding edge</a>
for documents with a predominately vertical writing direction.
One possible design of page headers for horizontally written documents uses the
''@top-left-corner'', ''@top-left'', ''@top-center'', ''@top-right'' and ''@top-right-corner''
page-margin boxes.
Another design, for vertically written documents, could use the
''@right-top'', ''@right-middle'', and ''@right-bottom'' page-margin boxes
for <a lt="right page">right facing pages</a> and
''@left-top'', ''@left-middle'', and ''@left-bottom''
for <a lt="left page">left facing pages</a>.
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
''@bottom-left-corner'', ''@bottom-left'', ''@bottom-center'', ''@bottom-right'' and ''@bottom-right-corner''
page-margin boxes as the page footer.
The design of a vertically written document could use
the page-margin boxes of the binding edge of the page for the page footer.
</div>
Page-margin boxes are positioned with respect to the page area
and are independent of page orientation,
for example the top page-margin boxes are above the page area
in both portrait and landscape orientation.
The various page-margin boxes are defined
and illustrated in the diagram below:
<table id="margin-box-def" class="data">
<caption>Table 1 Page-Margin Box Definitions</caption>
<thead>
<tr>
<th>Box
<th>Description
<th>Placement
<tbody>
<tr id="top-margin-boxes-def">
<th id="top-left-corner-box-def">top-left-corner
<td>a fixed-size box defined by the intersection of the top and left margins of the
page box
<td><img src="images/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">
<tr id="top-left-box-def">
<th>top-left
<td>a variable-width box filling the top page margin between the top-left-corner
and top-center page-margin boxes
<td><img src="images/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">
<tr id="top-center-box-def">
<th>top-center
<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
page-margin boxes
<td><img src="images/TopCenterMarginBox.png" alt="the top center box with margin, border, and padding, centered within the page's top margin"
height="47" width="181">
<tr id="top-right-box-def">
<th>top-right
<td>a variable-width box filling the top page margin between the top-center and
top-right-corner page-margin boxes
<td><img src="images/TopRightMarginBox.png" alt="the top right box with margin, border, and padding, nested within the page's top margin"
height="47" width="181">
<tr>
<th id="top-right-corner-box-def">top-right-corner
<td>a fixed-size box defined by the intersection of the top and right margins of
the page box
<td><img src="images/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">
<tr id="left-margin-boxes-def">
<th id="left-top-box-def">left-top
<td>a variable-height box filling the left page margin between the top-left-corner
and left-middle page-margin boxes
<td rowspan="3"><img src="images/LeftMarginBoxes.png" alt="left-top, left-middle, and left-bottom page-margin boxes in the page box's left margin"
height="226" width="181">
<tr id="left-middle-box-def">
<th>left-middle
<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 page-margin boxes
<tr id="left-bottom-box-def">
<th>left-bottom
<td>a variable-height box filling the left page margin between the left-middle and
bottom-left-corner page-margin boxes
<tr id="right-margin-boxes-def">
<th id="right-top-box-def">right-top
<td>a variable-height box filling the right page margin between the
top-right-corner and right-middle page-margin boxes
<td rowspan="3"><img src="images/RightMarginBoxes.png" alt="right-top, right-middle, and right-bottom page-margin boxes in the page box's right margin"
height="226" width="181">
<tr id="right-middle-box-def">
<th>right-middle
<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 page-margin boxes
<tr id="right-bottom-box-def">
<th>right-bottom
<td>a variable-height box filling the right page margin between the right-middle
and bottom-right-corner page-margin boxes
<tr id="bottom-margin-boxes-def">
<th id="bottom-left-corner-box-def">bottom-left-corner
<td>a fixed-size box defined by the intersection of the bottom and left margins of
the page box
<td><img src="images/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">
<tr id="bottom-left-box-def">
<th>bottom-left
<td>a variable-width box filling the bottom page margin between the
bottom-left-corner and bottom-center page-margin boxes
<td><img src="images/BottomLeftMarginBox.png" alt="bottom left page-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">
<tr id="bottom-center-box-def">
<th>bottom-center
<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 page-margin boxes
<td style="vertical-align: middle;"><img src="images/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">
<tr id="bottom-right-box-def">
<th>bottom-right
<td>a variable-width box filling the bottom page margin between the bottom-center
and bottom-right-corner page-margin boxes
<td><img src="images/BottomRightMarginBox.png" alt="bottom right page-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">
<tr id="bottom-right-corner-box-def">
<th>bottom-right-corner
<td>a fixed-size box defined by the intersection of the bottom and right margins of
the page box
<td><img src="images/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">
</table>
<h3 id="margin-at-rules">At-rules for page-margin boxes</h3>
Page-margin boxes are created by
<a>margin at-rules</a>
inside the <a href="#page-context">page context</a>.
Authors should put these rules after any declarations in the page context
as legacy clients may not handle declarations
after margin at-rules correctly.
A <dfn id="margin-at-rule">margin at-rule</dfn> is an <a>at-rule</a>
that identifies the page-margin box
(e.g. ''@top-left'') and a block of descriptors
(said to be in the <dfn export id="margin-context">margin context</dfn>).
<div class="example">
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:
<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 page-margin boxes</h3>
As with the '':before'' and '':after'' pseudo-elements,
a specified ''content: normal'' on a page-margin box computes to ''content/none''.
A page-margin box is <dfn>generated</dfn>
if and only if the computed value of its 'content' property is not ''content/none''.
Otherwise, no box is generated, as for elements with ''display: none''.
<p class=note>
The 'display' property does not apply to page-margin boxes.
<div class="example">
The following style sheet creates a green box in each corner of the page
except the bottom-left corner.
<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-dimension">Computing Page-margin Box Dimensions</h3>
The width and height of each page-margin box is determined by the rules
below. These rules define the equivalent of CSS2.1 Sections 10.3 and