CSS3 module: Generated Content for Paged Media

Abstract

This module describes features often used in printed publications. Most of the specified functionality involves some sort of generated content where content from the document is adorned, replicated, or moved in the final presentation of the document. Along with two other CSS3 modules – multi-column layout and paged media – this module offers advanced functionality for presenting structured documents on paged media. This specification only applies to the ‘print’ media type.

Status of this document

This is a public copy of the editors' draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don't cite this document other than as work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-gcpm” in the subject, preferably like this: “[css3-gcpm] …summary of comment…”

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This WD describes functionality at various levels of maturity. Some features have been part of other WDs in the past and have already been implemented. These parts are fairly stable and unlikely to change much. Other features are still at the sketching stage. In general, features presented earlier in this draft are more mature that those presented later in the draft.

Table of contents

• 1 Dependencies on other modules
• 2 Introduction
• 3 Running headers and footers
  • 3.1 Named strings
    • 3.1.1 Setting named strings: the ‘string-set’ property
    • 3.1.2 Using named strings
  • 3.2 Running elements
• 4 Leaders
• 5 Cross-references
  • 5.1 The ‘target-counter’ and ‘target-counters’ values
  • 5.2 The ‘target-text’ value
• 6 Footnotes
  • 6.1 Turning elements into footnotes
  • 6.2 The footnote area
  • 6.3 Footnote calls
  • 6.4 Footnote markers
  • 6.5 Counting footnotes
  • 6.6 Laying out footnotes
  • 6.7 Footnote magic
• 7 Border parts
  • 7.1 The ‘border-parts’ properties
• 8 Pulling elements: the ‘target-pull()’ value
• 9 Pushing elements: named flows
• 10 Hyphenation
  • 10.1 Hyphenate properties
  • 10.2 Named counter styles
  • 10.3 The ‘symbols()’ list-style-type
• 11 Character substitution
  • 11.1 The ‘text-replace’ property
• 12 Image resolution
• 13 Page marks and bleed area
• 14 Bookmarks
• 15 CMYK colors
• 16 Creating paged presentations
• 17 Styling blank pages
• 18 Page floats
• 19 Advanced multi-column layout
  • 19.1 The ‘float-offset’ property
• 20 Page lists
  • 20.1 The ‘page’ property
• 21 Continuation markers
• 22 Change bars
• 23 Line numbers
• 24 Generated lists
  • 24.1 The prototype properties
  • 24.2 TOC
  • 24.3 Glossary
  • 24.4 Index
  • 24.5 A more complex example
• 25 Conformance
• 26 Appendix A: Default style sheet
• Acknowledgments
• References
  • Normative references
  • Other references
• Index
• Property index

1 Dependencies on other modules

This CSS3 module has normative references to the following other CSS3 modules:

• [CSS3LIST]
• [CSS3VAL]

This CSS3 module has non-normative references to the following other CSS3 modules:

• [CSS3COL]
• [CSS3PAGE]
• [[CSS3MULTICOL]]

2 Introduction

(This section is not normative.)

This specification describes features often used in printed publications. Some of the proposed functionality (e.g., hyphenation, the new list style types, and border segments) may also used with other media types. However, this specification is only concerned with the ‘print’ media type.

3 Running headers and footers

To aid navigation in printed material, headers and footers are often printed in the page margins. [CSS3PAGE] describes how to place headers and footers on a page, but not how to fetch headers and footers from elements in the document. This specification offers two ways to achieve this. The first mechanism is named strings which copies the text (without style, structure, or replaced content) from one element for later reuse in margin boxes. The second mechanism is running elements which moves elements (with style, structure, and replaced content) into a margin box.

3.1 Named strings

Named strings can be thought of as variables that can hold one string of text each. Named strings are created with the ‘string-set’ property which copies a string of text into the named string. Only text is copied; not style, structure, or replaced content.

h1 { string-set: title content() }

@page :right { @top-right { content: string(title) }}

3.1.1 Setting named strings: the ‘string-set’ property

The ‘string-set’ property accepts a comma-separated list of named strings. Each named string is followed by a content list that specifies which text to copy into the named string. Whenever an element with value of ‘string-set’ different from ‘none’ is encountered, the named strings are assigned their respective value.

For the ‘string-set’ property, <content-list> expands to one or more of these values, in any order:

<string>

a string, e.g. "foo"

<counter>

the counter() or counters() function, as per CSS 2.1 section 4.3.5

<content>

the ‘content()’ function returns the content of elements and pseudo-elements. The functional notation accepts an optional argument:

‘content()’

Without any arguments, the function returns the textual content of the element, not including the content of its ::before and ::after pseudo-element. The content of the element's descendants, including their respective ::before and ::after pseudo-elements, are included in the returned content.

‘content(before)’

The function returns the textual content of the ::before pseudo-element the content of the element.

‘content(after)’

The function returns the textual content of the ::after pseudo-element the content of the element.

‘content(first-letter)’

The function returns the first letter of the content of the element. The definition of a letter is the same as for :first-letter pseudo-elements.

The expected use for ‘content(first-letter)’ is to create one-letter headers, e.g., in dictionaries.

Named strings can only hold the result of one assignment; whenever a new assignment is made to a named string, its old value is replaced.

User agents, however, must be able to remember the result of more than one assignment as the ‘string()’ functional value (described below) can refer to different assignments.

The scope of a named string is the page of the element to which the ‘string-set’ property is attached and subsequent pages.

The name space of named strings is different from other sets of names in CSS.

The ‘string-set’ property copies text as well as white-space into the named string.

h2 { 
  string-set: header "Chapter " counter(header) ": " content();
  counter-increment: header;
}

h2:before { content: "Chapter " counter(header) } 
h2 { 
  string-set: header content(before) content();
  counter-increment: header } 

dt { string-set: index content(first-letter) }

h1 { 
  display: none;
  string-set: header content();
}

3.1.2 Using named strings

The content of named strings can be recalled by using the ‘string()’ value on the ‘content’ property. The ‘string()’ value has one required argument, namely the name of the string.

@page { @top-center { content: string(header) }}
@page { @right-middle { content: string(index) }}
@page { @top-left { content: string(entry) }}
h1 { string-set: header "Chapter " counter(chapter) content() }
dt { string-set: index content(first-letter), entry content() }

If the value of the named string is changed by an element on a certain page, the named string may have several values on that page. In order to specify which of these values should be used, an optional argument is accepted on the ‘string()’ value. This argument can have one of four keywords:

• ‘start’: the named string's entry value for that page is used.
• ‘first’: the value of the first assignment is used. If there is no assignment on the page, the start value is used. ‘first’ is the default value.
• ‘last’: the named string's exit value for that page is used
• ‘first-except’: similar to ‘first’, except on the page where the value was assigned. On that page, the empty string is used.

@page { @top-left { content: string(term, first) }}
@page { @top-right { content: string(term, last) }}
@page { @top-center { content: string(index, first) }}
dt { string-set: index content(first-letter), term content() }

@page { @top-center { content: string(chapter, first-except) }}
h1 { string-set: chapter content() }

If the named string referred to in a ‘string()’ value has not been assigned a value, the empty string is used.

title { position: running(header) }
@page { @top-center {
  content: element(header) }
}

<style>
  div.header { display: none }
  @media print {
  div.header {
    display: block;
    position: running(header);
  }
  @page { @top-center { content: element(header, first-except) }}
</style>
...
<div class="header">Introduction</div>
<h1 class="chapter">An introduction</div>

...
<style>
@page { @top-center {
  content: element(header, first) }}
.header { position: running(header) }
.once { font-weight: bold }
</style>
...
<div class="header">Not now</div>
<p>Da di ha di da di ...
  <span class="header once">NOW!</span>
  <span class="header">Not now</span>
  ... da di ha di hum.</p>
...

4 Leaders

A leader is a visual pattern that guides the eye. Typically, leaders are used to visually connect an entry in a list with a corresponding code. For example, there are often leaders between titles and page numbers in a table of contents (TOC). Another example is the phone book where there are leaders between a name and a telephone number.

In CSS3, a leader is composed of series of glyphs through the ‘leader()’ value on the ‘content’ property. The functional notation accepts one value which describes the glyph pattern that make up the leader. These values are allowed:

• leader(dotted)
• leader(solid)
• leader(space)
• leader(<string>)

Using the keyword values is equivalent to setting a string value. The table below shows the equivalents:

Can leaders also be composed of images or SVG?

The string inside the parenthesis is called the leader string.

In its simplest form, the ‘content’ property only takes one ‘leader()’ value:

heading::after { content: leader(dotted) }

The leader string must be shown in full at least once and this establishes the minimum length of the leader. To fill the available space, the leader string is repeated as many times as possible in the writing direction. At the end of the leader, a partial string pattern may be shown. White space in leaders is collapsed according to the values on white-space properties.

These properties influence the appearance of leaders: all font properties, text properties, ‘letter-spacing’, white-space properties, background properties, and ‘color’.

User Agents should attempt to align corresponding glyphs from the leader pattern between consecutive lines.

In a more complex example, the ‘leader’ value is combined with other values on the ‘content’ property:

ul.toc a::after {
  content: leader(". . . ") target-counter(attr(href, url), page);
}

If the content connected by a leader end up on different lines, the leader will be present on all lines. Each leader fragment honors the minimum length of the leader.

<style>
.name::after { content: leader(dotted) }
</style>
<div class="entry">
<span class="name">John Doe</span>
<span class="number">123456789</span>
</div>

John Doe....
...123456789

To determine the length of the leaders, user agents must do the following for each line:

1. Lay out the content with leaders of minimum lengths
2. Determine the empty space left on the line.
3. Distribute the empty space between the leaders on the line. Glyphs must not be shown partially. All leaders on the line should, to the extent possible, have the same length. This may not always be possible as the minimum leader length must be honored.
4. Fill the empty space with the specified leader pattern.

<style>
cite::before { content: leader('  ') }
</style>
<blockquote>
  Bla great bla bla world bla bla
  empire bla bla color bla bla
  history bla bla forever.
    <cite>John Johnson</cite>
</blockquote>

  Bla great bla bla world bla bla
  empire bla bla color bla bla
  history bla bla forever.   John 
  Johnson

  Bla great bla bla world bla bla
  empire bla bla color bla bla
  history bla bla forever.
                     John Johnson

cite { text-wrap: suppress }

cite { white-space: nowrap }

  Bla great bla bla world bla bla empire
  bla bla color bla bla history bla bla 
  forever.                  John Johnson

5 Cross-references

It is common to refer to other parts of a document by way of a section number (e.g., "See section 3.4.1"), a page number (e.g., "See discussion on page 72"), or a string (e.g., "See the chapter on Europe"). Being able to resolve these cross-references automatically saves time and reduces the number of errors.

5.1 The ‘target-counter’ and ‘target-counters’ values

Numerical cross-references are generated by ‘target-counter()’ and ‘target-counters()’ values that fetch the value of a counter at the target end of the link. These functions are similar to the ‘counter()’ and ‘counters()’ functions, except that they fetch counter values from remote elements. ‘target-counter()’ has two required arguments: the url of the link, and the name of a counter. ‘target-counters()’ has three required arguments: the url of the link, the name of a counter, and a separator string. Both functions accepts an optional argument at the end that describes which list style type to use when presenting the resulting number; ‘decimal’ being the default.

a::after { content: "(see page " target-counter(attr(href, url), page, decimal) ")" }

a::after { content: "(see section " target-counters(attr(href, url), section, ".", decimal) ")" }

5.2 The ‘target-text’ value

Textual cross-references are generated by ‘target-text()’ which fetches the textual content from the target end of the link. Only text is copied; not style, structure, or replaced content. ‘target-text()’ has one required argument: the url of the link. An optional second argument specifies exactly which content is fetched. There are four possible values:

‘content()’

refers to the textual content of the element, not including the content of its ::before and ::after pseudo-element. The content of the element's descendants, including their respective ::before and ::after pseudo-elements, are included in the returned content.

‘content(before)’

refers to the content of the element's ::before pseudo-element. This is the default value.

‘content(after)’

refers to the content of the element's ::after pseudo-element

‘content(first-letter)’

refers to the first letter of the textual content of the element, not including the content of its ::before and ::after pseudo-element.

<p>See <a href="#chx">this chapter</a> for an in-depth evaluation.
...
<h2 id="chx">A better way</h2>

h2 { counter-increment: chapter }
a { content: "Chapter " target-counter(attr(href, url), chapter) 
   ' ("'  target-text(attr(href), content()) '") on page '
   target-counter(attr(href, url), page);

6 Footnotes

A footnote is a note typically placed at the bottom of a page that comments on or cites a reference. References to footnotes are marked with a note-call in the main text. The rendering of footnotes is complex. As far as possible, footnotes try to reuse other parts of CSS. However, due to the typographic traditions of footnotes, some new functionality is required to support footnotes in CSS:

In order to support footnotes in CSS, the following functionality is added:

• one new value on the ‘float’ property: ‘footnote’
• one new page area: ‘@footnote’
• two new pseudo-elements: ‘::footnote-call’ and ‘::footnote-marker’
• one predefined counter: ‘footnote’
• one new value on the ‘content’ property: ‘target-pull()’
• border segments
• two new ‘list-style-type’ values: ‘super-decimal’, and symbol(...)

<style>
.footnote { float: footnote }
</style>

<p>A sentence consists of words. <span class="footnote">Most often.</span>.

A sentence consists of words. ¹

¹ Most often.

<style>
@media print {
  .footnote { 
    float: footnote;
    content: target-pull(attr(href, url)) }
  .call { display: none }
}
</style>
...
<p>A sentence consists of words<a class="footnote" href="#words"> [3]</a>.
...
<p id=words><span class="call">[3]</span> Most often.

A sentence consists of words¹.

¹ Most often.

<p>Sorry, <span title="This is, of course, a lie.">we're closing for lunch</span>.

span[title]::after { 
  content: attr(title);
  float: footnote;
}

6.1 Turning elements into footnotes

An element with ‘float: footnote’ (called a footnote element) is moved to the footnote area and a footnote-call pseudo-element is put in its original place.

span.footnote { 
  float: footnote;
}

For each new footnote element, the ‘footnote’ counter is automatically incremented.

Footnote elements are presented inside the footnote area, but they inherit through their normal place in the structure of the document.

6.2 The footnote area

All elements with ‘float: footnote’ are moved to the footnote area. The footnote area is described by an @footnote-rule inside the @page-rule. By default, the footnote area appears at the bottom of the page, but it can be positioned using page floats (as described below) and ‘position: fixed’.

@page {
  @footnote { 
    float: bottom page;
    width: 100%;
  }
}

@page {
  @footnote { 
    position: fixed;
    top: 10em;
    left: 3em;
    width: 5em;
  }
}

@page {
  @footnote { 
    float: bottom left multicol;
    width: 1gr;
  }
}

The content of the footnote area is considered to come before other content which may compete for the same space on the same page.

@page { @footnote { float: bottom page}}
div.figure { float: bottom page }

Potentially, every page has a footnote area. If there are no footnotes on the page, the footnote area will not take up any space. If there are footnotes on a page, the layout of the footnote area will be determined by the properties/values set on it, and by the footnote elements inside it.

These properties apply to the footnote area: ‘content’, ‘border’, ‘padding’, ‘margin’, ‘height’, ‘width’, ‘max-height’, ‘max-width’, ‘min-height’, ‘min-width’, the background properties.

@footnote {
  margin-top: 0.5em;
  border-top: thin solid black;
  border-length: 4em; /* border-parts: 4em */
  padding-top: 0.5em;
}

6.3 Footnote calls

When an element is moved to the footnote area, a footnote-call is left behind. By default, User Agents must behave as if this code is part of the default style sheet:

::footnote-call {
  content: counter(footnote, super-decimal);
}

The resulting note call is a super-script decimal number.

6.4 Footnote markers

A ::footnote-marker pseudo-element is added to each footnote element. User agents must, by default, show the "footnote" counter in the footnote-marker.

::footnote-call {
  content: counter(footnote, super-decimal);
}
::footnote-marker {
  content: counter(footnote, super-decimal);
}

Marker elements are discussed in more detail in the CSS Lists module [CSS3LIST]. One suggested change to that module is to honor the value of ‘list-style-position’ on the ::footnote-marker pseudo-element itself rather than the corresponding list-item element. Further, one clarification to the horizontal placement of the marker is suggested: the margin box of the marker box is horizontally aligned with the start of the line box.

6.5 Counting footnotes

The "footnote" counter is automatically incremented each time a footnote is generated. That is, the "footnote" counter is incremented by one each time an element with ‘float: footnote’ appears.

The footnote counter can be reset with the ‘counter-reset’ property.

@page { counter-reset: footnote }

Should one also be able to manually increment the "footnote" counter?

6.6 Laying out footnotes

Footnotes must appear as early as possible under the following constraints:

1. A footnote marker may not appear on an earlier page than the footnote call.
2. Footnotes may not appear out of document order.
3. The footnote area is limited in size by ‘max-height’, unless the page contains only footnotes. (E.g., if at the end of the document there are still footnotes unprinted, the User Agent can use the whole page to display footnotes.)
4. If there is a footnote call on a page, the footnote area may not be empty, unless its ‘max-height’ is too small.

6.7 Footnote magic

When rendering footnotes, User Agents may apply certain heuristics to improve the presentation. For example, the space between a footnote-call and surrounding text may be adjusted. Another example is the height of the footnote area; it may be heuristically constrained to limit the area that is used for footnotes.

The "footnote" counter represents another kind of magic; it is automatically created and incremented each time an element is turned into a footnote, and the footnotes and footnote-calls are automatically labeled with the value of the footnote counter.

7 Border parts

CSS borders traditionally cover an entire border edge. Sometimes, however, it can be useful to hide some parts of the border.

7.1 The ‘border-parts’ properties

These properties split their respective borders into parts along the border edge. The first part is visible, the second is invisible, the third part is visible, etc. Parts can be specified with lengths, percentages, fractions (expressed by the ‘fr’ unit, as per [CSS3GRID] or its editor's edition), and the ‘repeat()’ function. The ‘normal’ value means that the border is not split, but shown normally.

‘border-parts’ is a shorthand property for the four individual properties.

If the listed parts are shorter than the border, any remaining border is split proportionally between the specified fractions. If there are no fractions, the behavior is as if ‘1fr’ had been specified at the end of the list.

If the listed parts are longer than the border, the specified parts will be shown in full until the end of the border. In this case, all fractions will be zero.

For horizontal borders, parts are listed from left to right. For vertical borders, parts are listed from top to bottom.

The ‘repeat()’ function specifies a "repeat pattern" that is repeated as many times as possible. Only one ‘repeat()’ function is allowed in a value. The repeat pattern must contain at least one length or percentage, otherwise the declaration must be ignored. The exact border parts are determined by laying out the specified border parts with all fractions initially set to zero. The border parts specified before and after the ‘repeat()’ function are laid out first. Thereafter, the repeat pattern is inserted between them at least once, and as many times as possible without making the sum of border parts longer than the border length. Any remaining border is split proportionally between the fractions specified.

The value of the repeat() function is disputed.

The exact border parts are determined by laying out the specified border parts with all fractions initially set to zero. Any remaining border is split proportionally between the fractions specified.

border-parts: 10px 1fr 10px;

border-parts-top: 10px 1fr 10px;
border-parts-bottom: 10px 1fr 10px;
border-parts-right: 5px 1fr 5px;
border-parts-left: 5px 1fr 5px;

border-parts-top: 0 10px 1fr 10px;
border-parts-bottom: 0 10px 1fr 10px;
border-parts-right: 0 5px 1fr 5px;
border-parts-left: 0 5px 1fr 5px;

border: thin solid black;
border-parts: 0 1fr; /* hide borders */
border-parts-top: 10px 1fr 10px; /* make certain borders visible */
border-parts-bottom: 10px 1fr 10px;

border-top: thin solid black;
border-bottom: thin solid black;
border-parts-top: 10px;
border-parts-bottom: 10px;

border-top: thin solid black;
border-parts: 10px;

A sentence consists of words¹.

¹ Most often.

@footnote {
  border-top: thin solid black;
  border-parts: 4em;
}

border: 2px solid black;
border-top-parts: repeat(10px 10px);

border: 2px solid black;
border-top-parts: repeat(10px 10px);

border: 2px solid black;
border-top-parts: repeat(10px 10px) 1fr;

border: 4px solid black;
border-top-parts: 40px 20px 0 1fr repeat(20px 20px) 0 1fr 40px;

border: 4px solid black;
border-top-parts: 40px 20px 0 1fr 20px 20px 0 1fr 40px;

border: 4px solid black;
border-parts-top: 3fr 10px 2fr 10px 1fr 10px 10px 10px 1fr 10px 2fr 10px 3fr;

<style>
@media print {
  .footnote { 
     float: footnote; 
     content: target-pull(attr(href, url)) }
  .footnote::footnote-call { content: counter(footnote, super-decimal) }
  .footnote::footnote-marker { content: counter(footnote, super-decimal) }
  .marker { display: none }
}
</style>
...
<p>A sentence consists of words<a class="footnote" href="#words"> [3]</a>.</p>
...
<p id="words"><span class="marker">[3]</span> Most often.</p>

.note { 
  float: to(endnote);
}
div.chapter::after { content: from(endnote) }

<contrib contrib-type="author">
  <name>
    <surname>Knuth</surname>
    <given-names>Donald E.</given-names>
  </name>
  <role>professor</role>
</contrib>

surname { float: to(lastname) }
given-names::after { content: from(lastname) }
role::before { content: ", " }

Donald E. Knuth, professor

table .note { float: to(tablenote); counter-increment: tablenotes }
table .note::note-marker { content: counter(tablenotes, super-decimal) }
table .note::note-call { content: counter(tablenotes, super-decimal) }
table::after { content: from(tablenote) }

.remove { to(dev-null) }

.remove { display: none }

.note { 
  float: to(sidenote);
}
@page :left {
  @left-bottom {
    content: from(sidenote);
  }
}
@page :right {
  @right-bottom {
    content: from(sidenote);
  }
}

10 Hyphenation

10.1 Hyphenate properties

This specification defines six new properties to describe hyphenation.

Values are:

none

Words are not broken at line breaks, even if characters inside the word suggest line break points.

manual

Words are only broken at line breaks where there are characters inside the word that suggest line break opportunities. Characters can be explicit or conditional.

In Unicode, U+00AD is a conditional "soft hyphen" and U+2010 is an explicit hyphen. Unicode Standard Annex #14 describes the role of soft hyphens in the Unicode Line breaking algorithm.

In HTML, &shy; represents the soft hyphen character which suggests a line break opportunity.

ex­ample.

auto

Words can be broken at appropriate hyphenation points, as determined by characters inside the word, resources listed in ‘hyphenate-resource’, or other UA-dependent resources. Characters inside the word take priority over hyphenation points determined by other resources.

This property specifies a comma-separated list of external resources that can help the UA determine hyphenation points. If more than one resource is specified, the UA should consult each resource until it finds one that is able to determine hyphenation points in a word. The ‘none’ value indicates that no external resources are available. In any case, the UA can also use local resources not listed on this property.

:lang(dk) { hyphenate-resource: url("hyph_da_DK.dic"), url("hyph_da_NO.dic") }

This property specifies the minimum number of characters in a hyphenated word before the hyphenation character. The ‘auto’ value means that the UA chooses a value that adapts to the current layout.

Unless the UA is able to calculate a better value, it is suggested that ‘auto’ means 2.

This property specifies the minimum number of characters in a hyphenated word after the hyphenation character. The ‘auto’ value means that the UA chooses a value that adapts to the current layout.

Unless the UA is able to calculate a better value, it is suggested that ‘auto’ means 2.

This property indicates the maximum number of successive hyphenated lines in an element. In some cases, user agents may not be able to honor the specified value. The ‘no-limit’ value means that there is no limit.

This property specifies a string that is shown when a hyphenate-break occurs. The ‘auto’ value means that the User Agent should find an appropriate value.

article { hyphenate-character: "\2010" }

10.2 Named counter styles

CSS defines a number of predefined list style types for the ‘list-style-type’ property and other places where a list-style-type value is accepted. Some styles repeat the same glyph (e.g., ‘disc’ and ‘circle’) while others have lists of glyphs (e.g., ‘decimal’, and ‘lower-roman’). To increase the range of lists that can be achieved through CSS without adding many new keywords, @counter-style rules are introduced. By using @counter-style, a style sheet can name new counter styles.

An @counter-style rule consists of the keyword ‘@counter-style’, followed by the name of the symbol counter style, followed by a space-separated list of strings.

@counter-style daggers "*" "\2020" "\2021" "\A7" "#";
ol { list-style-type: daggers }

@counter-style ordinal "1st" "2nd" "3rd" "4th";
h1:before { content: counter(chapter, ordinal) " chapter" }

The first string in the list represents number one, the second string represents number two, etc. Outside the range of specified values, the rendering will be as if the ‘decimal’ list style type had been specified.

@counter-style ordinal "1st" "2nd" "3rd" "4th";
ordered-list { counter-reset: items -1 }
list-item { counter-increment: items 2 }

Named counter styles can be imported through @import statements.

@import url(http://www.example.com/armenian-counters.css); /* defines 'armenian' */
ol { list-style-type: armenian }

10.3 The ‘symbols()’ list-style-type

A new list-style-type with a functional notation is introduced to avoid the indirection of having to name counter styles. The ‘symbols()’ value takes a comma-separated list of strings as arguments.

::footnote-call {
    content: counter(footnote, symbols('*', '+', '!'))
}

Outside the range of specified values, the rendering will be as if the ‘decimal’ list style type had been specified.

ol { list-style: symbols("*", "\2020", "\2021", "\A7", "#") }

body { text-replace: "'" "\2019" }

body { text-replace: "--" "\2014" }

body { text-replace: "..." "\2026" }

body { text-replace: "Soviet Union" "Russia" }

body { text-replace: "a" "b" "b" "c" }
body { text-replace: "a" "c" "b" "c" }

html { text-replace: "a" "b" }
body { text-replace: "c" "d" }

body { text-replace: "a" "" }

p { text-replace: "Soviet Union" "Russia"; }

<p>Hello Soviet Union!</p>
<p>Hello Soviet
Union!</p>

p { 
  text-replace: "Soviet Union" "Russia"; 
  white-space: pre;
}

<p>Hello Soviet Union!</p>
<p>Hello Soviet
Union!</p>

body { text-replace: 's/"([^"]*?)"/«$1»/g' }

body { text-replace: '"' '«' '»' }

body { text-replace: "Soviet Union" "Russia", '"' '«' '»' }

*::text("Soviet Union") { content: "Russia" }

12 Image resolution

Image resolution, as the term is used in this document, means pixels per physical length, e.g., pixels per inch. Some image formats can record information about the resolution of images. This information can be helpful when determining the actual size of the image in the formatting process. However, the information can also be wrong, in which case it should be ignored. The ‘image-resolution’ property is introduced to determine the correct resolution of images.

This property accepts either a single value, or a comma-separated list of two values. The values are:

normal

The resolution of the image is unknown, and UAs must not use the resolution found in the image. Instead, the image resolution will be found by making image pixels equivalent to CSS pixels.

from-image

The UA must look for the resolution in the image itself.

<dpi>

The value consists of a number with a ‘dpi’ unit identifier. The UA must use the specified resolution.

If the ‘from-image’ keyword is combined with a dpi value, the resolution of the image is used if it can be found. Otherwise, the specified resolution is used.

img { image-resolution: from-image }

img { image-resolution: from-image 300dpi }
img { image-resolution: 300dpi from-image }

img { image-resolution: 300dpi }

13 Page marks and bleed area

The ‘marks’ property from [CSS2] is part of this specification.

This property adds crop and/or cross marks to the document. Crop marks indicate where the page should be cut. Cross marks are used to align sheets.

Crop marks and cross marks are printed outside the page box. To have room to show crop and cross marks, the final pages will have to be somewhat bigger than the page box.

@page { marks: crop cross }

This property specifies the extent of the page bleed area outside the page box. This property only has effect if crop marks are enabled.

14 Bookmarks

Some document formats have the capability of holding bookmarks. Bookmarks are typically shown outside the document itself, often a tree-structured and clickable table of contents to help navigate in the electronic version of the document. To generate bookmarks, these properties are defined:

This property describes what level a certain bookmark has in a hierarchical bookmark structure. The highest level is ‘1’, then ‘2’, ‘3’ etc.

h1 { bookmark-level: 1 }
h2 { bookmark-level: 2 }
h3 { bookmark-level: 3 }

This property specifies the label of the bookmark, i.e., the text that will represent the bookmark in the bookmark structure.

a { bookmark-label: attr(title, string) }
h1 { bookmark-label: content() }
h2 { bookmark-label: content(before) }
#frog { bookmark-label: "The green frog" }

This property specifies the target of the bookmark link.

.bookmark {
   bookmark-label: attr(title, string);
   bookmark-target: attr(href, url);
}
...
<a class="bookmark" title="The green pear" href="#pears"/>

This property describes the initial state of a bookmark.

* { bookmark-state: closed }
#open { bookmark-state: open }

15 CMYK colors

PDF can hold two types of CMYK values: device-specific and color-profile-specific. In the latter case, we may need to point to a color profile.

Printers do not use RGB colors, they (often) use CMYK: cyan, magenta, yellow and black. A new functional value allows style sheets to express CMYK colors.

h3 { color: cmyk(0.8, 0.5, 0.0, 0.3) }

The values representing the colors are between ‘0’ and ‘1’. Values outside this range are clipped.

Unless a color profile is specified, the cmyk() value refers to device-specific colors. A future version of this specification will describe how to link to color profiles.

It is not expected that screen-centric user agents support CMYK colors and it is therefore important that existing CSS color values can be combined with CMYK colors.

h3 {
  color: red;
  color: cmyk(0.5, 0.1, 0.0, 0.2);
}

16 Creating paged presentations

Printed publications are paged, while screen-based presentations of web pages are most often presented in a continuous manner with a scrollbar on the side. There are reasons to believe that screen-based presentations also could benefit from using paged presentations. There is nothing in web specifications that prevent browsers from adding a page-based mode today. However, most web content is authored and styled with a continuous presentation in mind. This could change if it becomes possible to describe paged presentations in style sheets.

The simplest way to signal that a paged presentation is preferable is to add a value to the ‘overflow’ property. For example:

body { overflow: paged }

One challenge when introducing paged presentations on screens is that the user will need navigational tools to reach the next and previous pages. For scrolled presentations, the user agent automatically provides scrollbars. This solution could also work for paged presentations. However, it must be expected that authors want to design their own navigational tools. For example, authors may want to make their own buttons from images. In order to separate the style and the presentation, these navigational tools should not be part of the document.

17 Styling blank pages

Blank pages that appear as a result of forced page breaks can be styled with the :blank pseudo-class.

h1 { page-break-before: left }

@page :blank {
  @top-center { content: "This page is intentionally left blank" }
}

The :blank pseudo-class has the same specificity as the :first pseudo-class. A page matched by :blank will still be matched by other page selectors.

h1 { page-break-before: left }

@page :blank {
  @top-center { content: none }
}

@page :right {
  @top-center { content: "Preliminary edition" }
  @bottom-center { content: counter(page) }
}

18 Page floats

Images and figures are sometimes displayed at the top or bottom of pages. Also, an element may be moved to the next page or not displayed at all if there is not enough room on its native page. These types of floats are called "page floats" in this specification.

To support page floats, the ‘float’ property is extended with several new values. In this list, the new values are listed and categorized (along with the existing ‘left’, ‘right’ and ‘none’ keywords, and the ‘footnote’ and ‘to()’ as described above):

• horizontal keywords: left right inside outside
• vertical keywords: top bottom
• reference keywords: page multicol
• modifier keyword: next
• other keywords: none hide footnote to() page()

The keywords can be combined to form more complex expressions.

.figure { 
  float: top next page;
}

Further, the ‘float’ property is extended to accept a comma-separated list of sets of keywords. If the first set of keywords cannot be honored with the element remaining on the current page, the second set of keywords will determine how the element is floated.

.figure { 
  float: none, top next page;
}

The new values have the following meaning:

inside

On a right page, this value is synonymous with ‘left’. On a left page, this value is synonymous with ‘right’.

outside

On a left page, this value is synonymous with ‘left’, On a right page, this value is synonymous with ‘right’.

page

Indicates that the page area is the containing block for the element.

multicol

Indicates that the multicol element is the containing block for the element.

top

This keyword indicates that the element is floated to the top of the flow root.

bottom

This keyword indicates that the element is floated to the bottom of the flow root.

next

The float is placed on top of the next page from its source location. If combined with ‘bottom’, the float is placed on the bottom of the next page.

page()

The element is floated to a named page. The named page is created for the element, unless a suitable named page already has been created by another ‘page()’ value. The name page should appear as early as possible, but any ‘next’ keywords should be honored.

The element is floated to one or more named pages of the type specified. These named pages are created for the purpose of showing the element, and they are presented as early as possible after the page from which they are displaced. If the element is not the first page float to be displaced from this page area to this named page name, its contents should continue on the last of the previously established named pages (unless precluded, for example by page-breaking properties).

hide

As if ‘display: none’ is set.

The keywords can be combined into sets this way:

• only one horizontal keyword can appear in a set
• only one vertical keyword can appear in a set
• at least one horizontal or vertical keyword must appear, except that ‘none’, ‘hide’, and ‘footnote’ must appear alone
• ‘next’ may appear once along with ‘page’
• keywords can appear in any order

.figure { 
  float: top page;
  width: 1gr;
}

.figure { 
  float: top next page;
  width: 1gr;
}

.figure { 
  float: top right multicol;
  width: 1gr;
}

@footnote { 
  float: bottom inside multicol; 
  width: 1gr;
}

.figure { 
  float: top;
}

.figure { 
  float: none, hide;
}

table.wide { 
  float: page(landscape);
}

table.wide { 
  page: landscape;
}

table { 
  float: page(landscape);
}

table { 
  float: page(landscape);
  page-break-before: always;
}

For non-replaced elements in horizontal text, values on ‘float’ that have a horizontal component (‘right’, ‘left’, ‘outside’, ‘inside’) will result in shrink-wrap width calculations as per CSS 2.1 section 10.3.5. Values that only have a vertical component (‘top’, ‘bottom’, ‘next’, not in combination with other values) will result in width calculations as per CSS 2.1 section 10.3.3. In vertical text, width calculations are vice versa.

19 Advanced multi-column layout

In paged media, it is common for figures, captions, images, and quotes to be laid out in certain positions for typographical reasons, rather than for structural (as in content order) reasons. For example, an image that illustrates a news story is often placed in the upper right corner of the article, irrespective of its order in the content. A poignant quote from the article may be shown in large type in the column gap, pushing aside text in both columns, to get the attention of the reader.

Basic multi-column layouts is described in a separated CSS3 module [CSS3COL]. This section extends multi-column functionality so that more advanced, but commonly used, layouts can be achieved.

The proposed functionality relies on three new components:

• one new value on float: ‘multicol’:
• one new property: ‘float-offset’
• one new unit: ‘gr’

The strategy for achieving advanced multi-column layout is similar to page floats; elements escape their normal flow root by setting a value on ‘float’. In the case of multi-column layout, the keyword is ‘multicol’ (instead of ‘page’) and it indicates that the element should floated wrt. the multi-column element instead of the column where it naturally occurs.

To further enhance positioning, the ‘float-offset’ property is introduced. It pushes elements in the opposite direction of the positional keywords, both horizontally and vertically.

The ‘gr’ unit is introduced to allow the grid lines of columns (and, potentially, tables) to be used in the positioning ans sizing of elements. Each column has one grid line on each side corresponding to the content edge of the content box.

The ‘gr’ unit has two purposes. When used on the ‘float-offset’ property it identifies a position by counting columns and gaps from the position established by the ‘float’ property. Fractions on the ‘gr’ unit refer to fractions of the last counted gap or column.

When used on the ‘width’ property, the ‘gr’ unit identifies a length by counting gaps and columns, starting at the point where the element naturally finds itself and continuing in the direction of box expansion. Fractions on the ‘gr’ unit refer to the last gap or column counted.

19.1 The ‘float-offset’ property

This property pushes floated elements in the opposite direction of the where they have been floated with ‘float’. If one value is specified, it is the horizontal offset. If two values are specified, the first is the horizontal and the second is the vertical offset. If an element has only been floated horizontally (e.g., by setting ‘float: right’), this property will only offset the float horizontally, even if a vertical value also has been specified. Likewise, if an element has only been floated vertically, this property will only offset the float vertically. If an element has been floated both horizontally and vertically, this property will offset both horizontally and vertically. If no vertical value has been specified, the vertical offset is set to zero.

If the ‘gr’ unit or percentage unit is used, it means that the middle of the float should be aligned with the specified grid line (or portion thereof).

If another unit is used, it means that the float is pushed a distance equal to the specified length.

‘float-offset’ is a good concept for moving a float into the right position. For completeness it should apply to absolute positioning as well. We should reuse existing naming conventions already in place for abspos elements (e.g., 'offset-left, ‘right’, or call it ‘shift left, ’shift right' etc.).

<html>
<style>
div {
  column-width: 15em;
  column-gap: 2em;               /* shown in red below */
  column-rule: thin solid black; /* shown in black below */
  padding: 1em;                  /* shown in blue below */
}
img {
  display: block;                /* shown in dark gray below */
}
</style>
<body>
<div>
Lorem ipsum dolor sit amet. Nam at jus.
<img src="foo"/>
Sed imp er di et ris. Cur abi tur et sapen.
...
</div>
</body>
</html>

img { float: right }

img { 
  float: bottom;
  width: 1gr;
}

div.figure { 
  float: top right multicol; 
  width: 1gr }

div.quote { 
  float: top left multicol; 
  float-offset: 2.5gr; 
  width: 1gr }

div.quote { 
  float: top right multicol; 
  float-offset: 2gr; 
  width: 1gr }

The floated element will never be pushed outside the content edges of the multicol element due to ‘float-offset’.

img {
  float: top right multicol;
  width: 3gr;
}

img {
  float: top right multicol;
  width: 2gr;
}

img {
  float: top right multicol;
  width: 1.5gr;
}

img { 
  float: top left multicol;
  float-offset: 1.5gr 50%;
  width: 8em;
}

img { 
  float: top left multicol;
  float-offset: 1.25gr 50%;
  width: 6em;
}

20 Page lists

In CSS 2.0, the ‘page’ property takes one value, and the value can be ‘auto’ or a named page.

In this specification, a space-separated list of named pages (called a "page list") is allowed in the ‘page’ property and the property is changed from inherited to non-inherited.

20.1 The ‘page’ property

The content of the element is laid out on the list of pages specified on this property. The values mean:

auto

A single ‘auto’ value means that the element is laid out on the established page list. If no page list has been established, unnamed pages are created as necessary.

one or more named pages, optionally followed by ‘auto’

The element is laid out on the named pages specified in the page list. A page break is generated before the element unless the first named page in the list is the same as the current page. If more pages are required than there are items in the page list, the last item is repeated so that the element can be displayed. If the page list ends with the ‘auto’ keyword, the page list continues after the end of the element, otherwise the page list reverts back to that of the parent element.

  <div class="chapter">
    <h1>The beginning</h1>
    ....
  </div>

  <div class="chapter">
    <h1>The end</h1>
    ....
  </div>

  @page chapter { 
    @top-center { content: string(title) }
  }
  @page chapter-start { 
    @top-center { content: none }
  }

  div.chapter { page: chapter-start chapter }
  h1 { string-set: title content() }

  @page chapter { 
    @top-center { content: string(title) }
  }
  @page chapter:first { 
    @top-center { content: none }
  }

  div.chapter { page: chapter; page-break-before: always; }
  h1 { string-set: title content() }

  <h1>The beginning</h1>
    ....
  <h1>The end</h1>
    ....

  @page chapter { 
    @top-center { content: string(title) }
  }
  @page chapter-start { 
    @top-center { content: none }
  }
  h1 { page: chapter-start chapter auto;
       string-set: title content() }

  <table>...</table>

  @page rotated { size: landscape }
  table { page: rotated }

  <div>
    <table>...</table>
    <table>...</table>
    <p>This text is rendered on a 'narrow' page</p>
  </div>

  @page narrow { size: 9cm 18cm }
  @page rotated { size: landscape }
  div { page: narrow }
  table { page: rotated }

p::before-page-break { 
   list-style-position: outside;
   content: url(to-arrow.png);
}
p::after-page-break { 
   list-style-position: outside;
   content: url(from-arrow.png);
}

p.change-start { 
  change-bar: thin solid red;
  change-bar-class: change1;
  change-bar-offset: 0.3em;
  change-bar-side: left; /* or right, inside, outside */
}

p.change-end { 
  change-bar-class: change1;
}

::line-number-left(5) { 
   font: 10pt serif; 
   content: counter(line);
}

@page { counter-reset: line }

...
<style>
  #toc { prototype: list }
  #toc-entry { 
    prototype-insert-position: current;
    font-size: 14pt }
  #toc-entry::after { content: leader('. ') source-counter(page) }
  h1.chapter { prototype-insert: #toc-entry content() }
</style>
...
<div id="toc">
  <h1>Table of contents</h1>
  <div id="toc-entry"></div>
</div>
...
<h1 class="chapter">Introduction</h1>
...

  #toc { prototype: list }

    prototype-insert-position: current;

  #toc-entry::after { content: leader('. ') source-counter(page)} 

  h1.chapter { prototype-insert: toc-entry content() }

...
<style>
#glossary { prototype: list }
#glossary-term { prototype-insert-position: sorted }
#glossary-definition { prototype-insert-position: current }
dfn { prototype-insert: glossary-term content(), glossary-definition attr(title) }

</style>
...
<div id="glossary">
<h2>Glossary of terms</h2>
<dl>
  <dt id="glossary-term">...</dt>
  <dd id="glossary-definition">...</dd>
</dl>
</div>
...

<p>The <dfn title="Leading paragraph">introduction</dfn> comes first.</p>

#glossary { prototype: container }
#glossary-term { prototype-insert-position: sorted  }
#glossary-definition { prototype-insert-position: current }
dfn { prototype-insert: #glossary-term content(), #glossary-definition attr(title) }

</style>
...
<table id="glossary">
	<th style="border: thin solid black">Term</th>
	<th style="border: thin solid black">Definition</th>
<tr id="glossary-term">
	<td></td>
	<td id="glossary-definition"></td>
</tr>
</table>
...
<p>The <dfn title="Leading paragraph">introduction</dfn> comes first.</p>

...
<style>
#index {
  prototype: list }
#index-marker {
  prototype-insert-position: sorted 
  prototype-insert-policy: unique; 
  text-transform: uppercase }
#index-entry {
  prototype-insert-position: sorted }
#index-entry::after {
  content: leader(". . ") source-counter(page) }
dfn.entry { 
  prototype-insert: #index-marker content(first-letter), #index-entry content() }
</style>
...

<div id="index">
<h2>Index</h2>
<div id="index-marker"></div>
<div id="index-entry"></div>
</div>

<p>An <dfn class="entry">emphasized element</dfn> stands out.</p>
...

<style>
#toc-list {
  prototype: list }

#toc-entry-section {
  font-size: large;
  prototype-insert-position: current }

#toc-entry-subsection {
  font-size: medium;
  prototype-insert-position: current }

#toc-entry-section::after, #toc-entry-subsection::after {
  content: leader('. ') source-counter(page) }

#acronym-list {
  prototype: list }

#acronym-term {
  prototype-insert-position: sorted }

#acronym-definition {
  prototype-insert-position: current }

#index {
  prototype: list }

#index-marker {
  prototype-insert-position: sorted 
  prototype-insert-policy: unique;
}

#index-entry {
  prototype-insert-position: sorted }

#index-entry::after {
  content: leader('. . ') source-counter(page) }

h2 {
  prototype-insert: #toc-entry content() }

h3 {
  prototype-insert: #toc-entry content() }

acronym { 
  prototype-insert:
          #index-marker content(first-letter), 
          #index-entry content(), 
          #acronym content(), 
          #acronym-definition attr(title);
}

dfn { prototype-insert: 
          #index-marker content(first-letter), 
          #index-entry content();
}
</style>

<div id="toc">
<h2>Table of contents</h2>
  <div id="toc-list">
    <div id="toc-entry-section"></div>
    <div id="toc-entry-subsection"></div>
  </div>
</div>

<div id="acronym-list">
<h2>List of acronyms</h2>
<dl>
  <dt id="acronym"></dt>
  <dd id="acronym-definition"></dd>
</dl>
</div>

<div id="index">
<h2>Index</h2>
<div id="index-marker"></div>
<div id="index-entry"></div>
</div>

<body>

<h2>Introduction</h2>

<p>This part defines the a acronym: <acronym title="HyperText
Markup Language">HTML</acronym>.

<h3>More to learn</h3>

<p>An <dfn>emphasized element</dfn> element stands out.

</body>

25 Conformance

26 Appendix A: Default style sheet

@page {
  counter-reset: footnote;
  @footnote {
    counter-increment: footnote;
    float: page bottom;
    width: 100%;
    height: auto;
  }
}

::footnote-call {
  counter-increment: footnote;
  content: counter(footnote, super-decimal); 
}
::footnote-marker {
  content: counter(footnote, super-decimal); 
}


h1 { bookmark-level: 1 }
h2 { bookmark-level: 2 }
h3 { bookmark-level: 3 }
h4 { bookmark-level: 4 }
h5 { bookmark-level: 5 }
h6 { bookmark-level: 6 }

Acknowledgments

This document has been improved by Bert Bos, Michael Day, Melinda Grant, David Baron, Markus Mielke, Steve Zilles, Ian Hickson, Elika Etemad, Laurens Holst, Mike Bremford, Allan Sandfeld Jensen, Kelly Miller, Werner Donné, Tarquin (Mark) Wilton-Jones, Michel Fortin, Christian Roth, Brady Duga, Del Merritt, Ladd Van Tol, Tab Atkins Jr., Jacob Grundtvig Refstrup, James Elmore, Ian Tindale, Murakami Shinyu, Paul E. Merrell, Philip Taylor.

References

Normative references

[CSS3LIST]

Ian Hickson; Tantek Çelik. CSS3 module: Lists. 7 November 2002. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2002/WD-css3-lists-20021107

[CSS3VAL]

Chris Lilley; Håkon Wium Lie. CSS3 Values and Units. 19 September 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-values-20060919

Other references

[CSS2]

Ian Jacobs; et al. Cascading Style Sheets, level 2 (CSS2) Specification. 11 April 2008. W3C Recommendation. URL: http://www.w3.org/TR/2008/REC-CSS2-20080411

[CSS3COL]

Håkon Wium Lie. CSS3 module: Multi-column layout. 6 June 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css3-multicol-20070606

[CSS3GRID]

Markus Mielke; Alex Mogilevsky. CSS Grid Positioning Module Level 3. 5 September 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-css3-grid-20070905

[CSS3PAGE]

Melinda Grant; Håkon Wium Lie. CSS3 Module: Paged Media. 10 October 2006. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2006/WD-css3-page-20061010

Index

• bleed, 13
• bookmark-label, 14
• bookmark-level, 14
• bookmark-state, 14
• bookmark-target, 14
• border-parts, 7.1
• border-parts-bottom, 7.1
• border-parts-left, 7.1
• border-parts-right, 7.1
• border-parts-top, 7.1
• float-offset, 19.1
• hyphenate-after, 10.1
• hyphenate-before, 10.1
• hyphenate-character, 10.1
• hyphenate-lines, 10.1
• hyphenate-resource, 10.1
• hyphens, 10.1
• image-resolution, 12
• marks, 13
• named strings, 3
• page, 20.1
• prototype, 24.1
• prototype-insert, 24.1
• prototype-insert-policy, 24.1
• prototype-insert-position, 24.1
• running elements, 3
• string-set, 3.1.1
• text-replace, 11.1

Property index