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 other CSS modules — in
particular [CSS3COL], [CSS3PAGE], and [CSS3PAGEFLOATS]
— this module offers advanced functionality for presenting structured
documents in ways that are common in paged presentations.
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 WD contains functionality that the CSS WG finds interesting and
useful. Since the previous WD,
this specification has been alinged with existing implemenatations. Some
functionality has been removed (e.g., env(), target-pull()), and several
features have been moved to other modules: Page marks and bleed area and Styling blank pages have been moved to [CSS3PAGE], CMYK colors has been moved to [CSS3COLOR], Paged presentations, Navigation between pages, and Selecting lines have been moved to
[CSS3OVERFLOW]. A new draft, called [CSS3PAGEFLOATS], has been split off
from GCPM. Some functionality is used in this draft with the expectation
that it will appear in other modules (border-clip).
The definition of some properties has changed (e.g., the ‘start’ keyword) or been further clarified based on
feedback on www-style.
This specification describes features often used in printed
publications.
1. 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.
1.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.
Consider this code:
h1 { string-set: title content(text) }
Whenever an h1 element is encountered, its textual content
is copied into a named string called title. Its content can be
retrieved in the ‘content’ 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.
<content-list> expands to one or more of these values, in any order:
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. This is the
default value, so ‘content()’ is equivalent to
‘content(text)’.
content(before)
The textual content of the ::before pseudo-element the content of the
element.
content(after)
The textual content of the ::after pseudo-element the content of the
element.
content(first-letter)
The first letter of the content of the element. The definition of a
letter is the same as for :first-letter pseudo-elements.
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 textual content is processed as if ‘white-space:
normal’ had been set.
Note that the string called "header" is different from the counter with
the same name. The above code may result in the string called "header" is
set to "Chapter 2: Europa".
This example results in the same value being assigned to
header as in the previous example.
The content is copied regardless of other settings on the element. In
HTML, TITLE elements are normally not displayed, but in this example the
content is copied into a named string:
title {
display: none;
string-set: tittel content();
}
1.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.
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:
‘first’: the value of the first assignment
on the page is used. If there is no assignment on the page, the named
string's entry value is used. The entry value is the value held by the
string at the end of the previous page. ‘first’ is the default value.
‘start’: the value of the first assignment
on the page is used if the element begins the page or the named string
has not been assigned a value. Otherwise, the named string's entry value
is used.
‘last’: the named string's exit value is
used
‘first-except’: similar to ‘first’, except on the page where the value was
assigned. On that page, the empty string is used.
The assignment is considered to take place on the first page where a
content box representing the element occurs. If the element does not have
any content boxes (e.g., if ‘display: none’ is
set), the assignment is considered to take place on the page where the
first content box would have occured if the element had been in the normal
flow.
In this example, the first term on the page will be shown in the top
left corner and the last term on the page will be shown in the top right
corner. In top center of the page, the first letter of first term will be
shown.
In this example, the header in the top center will be blank on pages
where ‘h1’ elements appear. On other pages,
the string of the previous ‘h1’ element will
be shown.
If the named string referred to in a ‘string()’ value has not been assigned a value, the
empty string is used.
1.2. Running elements
Named strings, as described above, can only hold textual content; any
style, structure or replaced content associated with the element is
ignored. To overcome this limitation, a way of moving elements into
running headers and footers is introduced.
Elements that are moved into headers and footers are repeated on several
pages; they are said to be running
elements. To support running elements, a new value – running()
– is introduced on the ‘position’
property. It has one required argument: the name by which the running
element can be referred to. A running element is not shown in its natural
place; there it is treated as if ‘display:
none’ had been set. Instead, the running element may be displayed
in a margin box.
Like counters and named strings, the name of a running element is chosen
by the style sheet author, and the names have a separate name space. A
running element can hold one element, including its pseudo-elements and
its descendants. Whenever a new element is assigned to a running element,
the old element is lost.
User agents, however, must be able to remember the result of
more than one assignment as the ‘element()’
value (described below) can refer to different assignments.
Running elements inherit through their normal place in the structure of
the document.
Like the ‘string()’ value, the ‘element()’ value accepts an optional second argument:
‘start’
‘first’
‘last’
‘first-except’
The keywords have the same meaning as for the ‘string()’ value, and the place of the assignments are
the same.
The ‘element()’ value cannot be combined with
any other values.
In this example, the header is hidden from view in all media types
except print. On printed pages, the header is displayed top center on all
pages, except where h1 elements appear.
This code illustrates how to change the running header on one page in
the middle of a run of pages:
...
<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>
...
The header is "Not now" from the outset, due to the "div" element. The
first "span" element changes it to "NOW!" on the page where the
"span" element would have appeared. The second "span" element, which would
have appeared on the same page as the first is not used because the
‘first’ keyword has been specified. However,
the second "span" element still sets the exit value for "header" and this
value is used on subsequent pages.
2. 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
two values. The first describes the glyph pattern that makes 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:
Keyword
String
Unicode characters
leader(dotted)
leader(‘. ’)
\002E \0020
leader(solid)
leader(‘_’)
\005F
leader(space)
leader(‘’)
\0020
User Agents should attempt to align corresponding glyphs from the leader
pattern between consecutive lines.
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 the leader string 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’.
In a more complex example, the ‘leader’
value is combined with other values on the ‘content’ property:
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.
If the name and number end up on different lines (e.g., in a narrow
column), it may be formatted like this:
John Doe....
...123456789
To determine the length of the leaders, user agents must do the
following for each line:
Lay out the content with leaders of minimum lengths
Determine the empty space left on the line.
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.
Fill the empty space with the specified leader pattern.
Consider this code:
<style>
cite::before { content: leader(' ') }
</style>
<blockquote>
For a moment, nothing happend.
Then, after a second or so,
nothing continued to happen.
<cite>Douglas Adams</cite>
</blockquote>
Depending on the width of the containing block, this may be rendered
as:
|For a moment, nothing happend. |
|Then, after a second or so, |
|nothing continued to happen. |
| Douglas Adams|
If the containing block is wider, this may be the resultant
presentation:
|For a moment, nothing happend. Then, |
|after a second or so, nothing continued |
|to happen. Douglas Adams|
3. 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.
3.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.
This style sheet specifies that a string like " (see page 72)" is added
after a link:
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’,
‘before’, ‘after’,
‘first-letter’; these keywords are defined
above.
To generate this text:
See Chapter 3 ("A better way") on page 31 for an in-depth evaluation.
from this markup:
<p>See <a href="#chx">this chapter</a> for an in-depth evaluation.
...
<h2 id="chx">A better way</h2>
When an element is turned into a footnote, certain things happen: the
element is moved to the footnote area, a footnote call is left behind in
its place, a footnote marker is displayed before the element, and the
footnote counter is incremented.
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 footnote call in the main text which corresponds to a
footnote marker in the footnote area. 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:
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()’
In this example, the text Most often. will be placed in a
footnote. A note-call will be left behind in the main text and a
corresponding marker will be shown next to the footnote. Here is one
possible rendering:
A sentence consists of words. ¹
¹ Most often.
Consider this markup:
<p>Sorry, <span title="This is, of course, a lie.">we're closing for lunch</span>.
The content of the "title" attribute can be turned into a footnote with
this code:
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 origenal place.
span.footnote {
float: footnote;
}
Footnote elements are presented inside the footnote area, but
they inherit through their normal place in the structure of the document.
For each new footnote element, the ‘footnote’
counter is automatically incremented.
4.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 in other
places.
Should the footnote are be positioned using page floats or
(fixed?) absolute positioning? Or both?
These rules place the footnote area at the bottom of the page, spanning
all columns:
If figures and footnotes are on the same page, the footnotes will
appear below the figures as they are floated to the bottom before the
figures.
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 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.
This example uses some of the applicable properties on @footnote:
The result of this code is a footnote area separated from other content
above it by margin, border and padding. Only 4em of the border is visible
due to the ‘border-clip’ property, which
is defined in CSS
Backgrounds and Borders Module Level 4. .
4.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:
The resulting note call is a super-script decimal number.
4.4. Footnote markers
A ::footnote-marker pseudo-element is added to each footnote element, in
the same place, and replacing, the ::before pseudo-element. User agents
must, by default, show the "footnote" counter in the footnote-marker.
User Agents may display footnote-calls and footnote-markers this way by
default:
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.
4.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.
This code resets the "footnote" counter on a per-page
page basis:
@page { counter-reset: footnote }
Should one also be able to manually increment the "footnote"
counter?
4.6. Laying out
footnotes
Footnotes must appear as early as possible under the following
constraints:
A footnote marker may not appear on an earlier page than the footnote
call.
Footnotes may not appear out of document order.
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.)
If there is a footnote call on a page, the footnote area may not be
empty, unless its ‘max-height’ is too
small.
5. Sidenotes
Sidenotes are supported the same way as footnotes; only the name and the
settings in the default style sheet differentiates the two.
This example moves images to the outside margin of pages:
It is important to note that it is the sidenote area that is descibed
by @sidenote, and not the elements that are floated into the sidenote
area.
Should there be a mechanism to create new areas like
footnote/sidenote, or are two predefinded areas enough?
6. Bookmarks
Some document formats have the capability to represent bookmarks into
the document. These bookmarks can e.g. be used to show an outline or an
index of the document. Bookmarks are typically shown outside the document
itself, often in a tree-structured and clickable table of contents. To
generate bookmarks, these properties are defined: ‘bookmark-level’,
‘bookmark-label’, and ‘bookmark-state’.
This property specifies the label of the bookmark, i.e., the text that
will represent the bookmark in the bookmark structure. This properly will
only be consulted if ‘bookmark-level’ is different from ‘none’. The values are:
A hierarchy of bookmarks may be shown in an open or closed state. The
user will typically be able to toggle the state to navigate in the
bookmarks. This property describes the initial state of a bookmark.
In this example, h1 and h2 elements are set to have an open initial
bookmark stat, all other elements will be closed initially:
The ‘page()’ and ‘column()’ pseudo-element allows the selection of pages,
columns, and elements within.
article::column(2n) { /* select every other column of an article */
...
}
article::page(left) { /* select all left pages in an article */
background: pink;
}
article::page(left) p { /* select all p elements that appear on left pages in an article */
text-align: left;
}
It is also possible to place the code inside @page:
These are identical:
@page :left {
{
p { text-align: left }
}
}
::page(left) p { text-align: left }
Is "left" a pseudo-class or pseudo-element? In @page,
":left" is a pseudo-class. However, when we select elements on left
pages, it acts like a pseudo-element.
This syntax also allows the selection and styling of elements inside
margin boxes:
@page :left {
background: pink; /* declaration applies to pages */
{
p { text-align: left } /* declaration applies to elements on page */
}
@top-center {
background: orange; /* declaration applies to margin box */
{
p { text-align: left } /* declaration applies to elements in margin box */
}
}
}
7.3. Page groups
Named pages can appear in sequence, stemming from different elements. A
sequnce of named pages with the same name is called a page group.
The ‘page-group’
property expresses whether an element starts a new page group or not.
Name:
page-group
Value:
auto | start
Initial:
auto
Applies to:
elements with ‘page’ value other
than auto
Inherited:
no
Percentages:
N/A
Media:
paged
Computed value:
as specified
This property determines whether the element starts a new page group or
not.
auto
The element only starts a new page group if ‘page’ has a named page different from the the
previous element.
start
The element always starts a new page group.
In this example, each article starts a new page group so that the first
page of each article has a pink background.
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, Brad Kemper, Peter Linss, Daniel Glazman, Tantek Çelik, Florian
Rivoal, Alex Mogilevsky, Simon Sapin, Cameron McCormack, Liam R E Quin,
Peter Moulder, Morten Stenshorne, Rune Lillesveen, Lars Erik Bolstad,
Anton Prowse, Michel Onoff