Overview.bs

<h1>CSS Generated Content for Paged Media Module Level 4</h1>
<pre class='metadata'>
Status: ED
Shortname: css-gcpm-4
Level: 4
Group: csswg
ED: http://dev.w3.org/csswg/css-gcpm-4/
Editor: Dave Cramer, Hachette Livre, dauwhe@gmail.com
Editor: Daniel Glazman, Disruptive Innovations, daniel.glazman@disruptive-innovations.com
Abstract: Level 4 of GCPM proposes a region-based approach to footnotes and running heads.
!Issue Tracking: <a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=CSS&component=Generated%20Content%20for%20Paged%20Media">W3C Bugzilla</a>
Ignored Terms: 
Warning: Not Ready
</pre>

<h2 class="no-num" id="introduction">
	Introduction
</h2>

There have been many proposals for using CSS to move document content, often motivated by the desire for magazine- or book-style layout of footnotes, running heads, pull quotes, sidebars, and so on. [[CSS3GCPM]] used float: footnote and position: running(). The now-abandoned [[CSS3GENCON]] Working Draft used content: footnote. PrinceXML (and older GCPM drafts) has content: flow() and flow: static(). WHATWG CSS Books has flow: area().

This module proposes a unified approach to paginated layout based on [[CSS3-REGIONS]] and [[CSS3-PAGE-TEMPLATE]]. Additional properties will be introduced as necessary. 




<!--page areas-->
<h2 id="running-headers-and-footers">
	Running headers and footers
</h2>
[[CSS3PAGE]] describes the sixteen page margin boxes which can be used for running headers and footers, but does not describe a mechanism for inserting content in those boxes. 

[[CSS3GCPM]] provides for copying the string values of elements into the existing page margin boxes. 

The existing mechanisms do not cover many use cases. 


<h3 id="copy-into-heading">Copying a flow: the 'copy-into' property</h3>

Headers often contain document content, and it is desirable to both display that content normally (for example, as an <code>h1</code>) and to use the content in a running head. [[CSS3-REGIONS]] allows for an element to be moved to a ''named flow'', but doesn't allow for using the same content in two ways. The 'copy-into' property allows an element to be copied into a content fragment which can then be placed with the 'content' property. 

<p class="note">Use cases for running heads can be found in [[LATINREQ] http://w3c.github.io/dpub-pagination/#content</p>



<pre class="propdef">
Name: <dfn id="copy-into-property">copy-into</dfn>
Value: none |  [ [ &lt;custom-ident>  &lt;content-level>] [,  &lt;custom-ident>  &lt;content-level>]*  ]?
Initial: none
Applies To: all elements and pseudo-elements, but not ::first-line or ::first-letter.
Inherited: no
Media: visual
Computed value: as specified
</pre> 

The 'copy-into' property contains one or more pairs, each consisting of a custom identifier followed by a content-level keyword describing how to construct the value of the named content fragment.

''content-level'' expands to the following values: 

<pre class="prod">
	<dfn id="content-list">content-list</dfn> = element | content | text | attr(&lt;identifier>) | counter() | counters()
</pre> 


<dl>

<dt>element</dt>
<dd>the entire element is copied into the named content fragment</dd>

<dt>contents</dt>

<dd>only the element’s contents are copied into the named content fragment. This is the default if ''content-level'' is not specified.

</dd>

<dt>text</dt>

<dd>only the element’s text (including normally collapsed white space) is copied into the named content fragment.
</dd>

</dl>

<div class="example">
<pre>
h1 { 
  copy-into: chapter-title element; 
  font-size: 1.5em;
}

@page {
  @top-center {
    content: chapter-title '.';
    font-size: .9em;
    font-variant: small-caps;
    }
}
</pre> 
</div>


<h3 id="flow-persist-heading">Choosing among multiple values on a page</h3>






<pre class="propdef">
Name: <dfn id="flow-persist-property">flow-persist</dfn>
Value: ( normal | persist | static ), ( start | first | last | first-except)?
Initial: normal
Applies To: all elements with a value of 'flow-from' other than none.
Inherited: no
Media: visual
Computed value: as specified
</pre> 





<div class="example">
Example using 'copy-from' syntax
<pre>
h1 { 
  copy-into: chapter-title; 
}

@page:left {
  @top-left {
    content: copy-from(chapter-title, first);
    }
}

@page:right {
  @top-right {
    content: copy-from(chapter-title, last);
    }
}
</pre>

</div>

<div class="example">
Example using selectors syntax
<pre>
h1:first-of-page { 
  copy-into: chapter-title-left; 
}

h1:last-of-page { 
  copy-into: chapter-title-right; 
}

@page:left {
  @top-left {
    content: chapter-title-left;
    }
}

@page:right {
  @top-right {
    content: chapter-title-right;
    }
}
</pre>

</div>

<h2 id="page-area-head">Creating Page Areas</h2>


[[CSS3-PAGE-TEMPLATE]] introduces @template and @slot rules. We propose to allow the use of @slot in the @page context, to allow greater flexibility than the page margin boxes in [[CSS3PAGE]]. These slots can also be used for sidenotes, pull quotes, footnotes, and many other document features.


<div class="example">

<pre>

@page body {
  @slot center-header {
    top: 0px;
    left: 1em;
    right: 1em;
    height: 2em;
    flow-from: header;
    flow-persist: persist;
    wrap-flow: clear;
  }
}

</pre>


</div>


<p class="issue">Is there a need for both @page and @template?</p>





<h2 id="footnotes">
	Footnotes
</h2>
Ancillary content may be moved to the bottom or side of a page. A footnote is created when such content moves to the bottom of the page, leaving a reference indicator. 


<h3 id="footnote-terms">Terminology</h3>

Footnotes are complex objects, so it will be helpful to define some terms before proceeding. 

<figure>


<img src="images/footnote-diagram.001.jpg" width="480" alt="page with footnotes"/>
<figcaption>Footnote terminology</figcaption>
</figure>

<dl>



<dt>footnote element</dt>
<dd>The element containing the content of the footnote, which will be removed from the flow and displayed as a footnote.</dd>

<dt>footnote marker (also known as footnote number)</dt>
<dd>A number or symbol adjacent to the footnote body, identifying the particular footnote. The footnote marker should use the same number or symbol as the corresponding footnote call, although the marker may contain additional punctuation.</dd>

<dt>footnote body</dt>
<dd>The footnote marker is placed before the footnote element, and together they represent the footnote body, which will be placed in the footnote area.</dd>

<dt>footnote call (also known as footnote reference)</dt>
<dd>A number or symbol, found in the main text, which points to the footnote body.</dd>


<dt>footnote area</dt>
<dd>The page area used to display footnotes.</dd>

<dt>footnote rule (also known as footnote separator)</dt>
<dd>A horizontal rule is often used to separate the footnote area from the rest of the page. The separator (and the entire footnote area) cannot be rendered on a page with no footnotes.</dd>

</dl>

<h3 id="footnotes-as-regions">Footnotes as Regions</h3>


<div class="example">
HTML: 
<pre style="word-wrap: break-word; white-space: pre-wrap;">
&lt;p>Though the body was erect, the head was thrown back so that the closed eyes were pointed towards the needle of the tell-tale that swung from a beam in the ceiling..&lt;span class="reference">&lt;span class="footnote">The cabin-compass is called the tell-tale, because without going to the compass at the helm, the Captain, while below, can inform himself of the course of the ship.&lt;/span>&lt;/span>&lt;/p>
</pre> 
CSS: 
<pre>
span.footnote {
  flow-into: footnote;
  flow-policy: copy;
  display: block;
}

span.footnote::before {
  content: counter(footnote) '. ';
}

span.reference::before {
  content: counter(footnote);
  font-variant-position: super;
}

@page {
  @slot footnote {
    flow-from: footnote;
    required-flow: footnote;
    position: absolute;
    left: 54pt;
    bottom: 0pt;
    width: 352pt;
    height: auto;
    border-top: .25pt solid black;
    vertical-align: bottom; 
    wrap-flow: clear;
  }
}
</pre> 
</div>

<p class="issue">The above HTML contains two nested spans for the footnote, as CSS has no mechanism to leave a reference object where something was removed from the flow.</p>

<p class="issue">Would it be possible to specify <code>flow-into: none</code> on <code>span.footnote::after</code>? [[CSS3-REGIONS]] forbids the flow-into property on pseudo-elements, but should that be changed?</p>



<div class="example">
Inline footnote
<pre>
span.footnote {
  flow-into: footnote;
  display: inline;
}
</pre>
</div>





<!--<h2>Flow Properties from PGT (for reference)</h2>

<p class="note">For convenience, here are definitions of the flow properties used by [[EPUB-PGT]].</p>

<h3>flow-options</h3>
<pre class="propdef">
Name: <dfn id="flow-options-pgt">flow-options</dfn>
Values: none | [ exclusive || last || static 
Initial: none
Applies To: elements for which 'flow-into' property was specified
Inherited: no
Media: visual
Computed value: as specified
</pre> 

 <dl>
            <dt>exclusive</dt>
            <dd>When content is selected for a partition, elements marked as exclusive are
                considered first. Only one exclusive element is used for a single partition and one
                element is always consumed (and removed from the flow if it is not also marked as
                    <span class="val">static</span>).</dd>
            <dt>static</dt>
            <dd>When an element is consumed in a partition, it is removed from the flow, unless it
                is marked as <span class="val">static</span>. Static elements are placed in the flow
                again when they are consumed.</dd>
            <dt>last</dt>
            <dd>When this option is applied to elements which are also marked <span class="val"
                    >exclusive</span>, the last of them is flowed in the next available
                partition.</dd>
        </dl>

<h3>flow-linger</h3>

The 'flow-linger' property determines how many pages an element is eligible for on a page. None means it stays eligible until consumed. <integer> must be positive and means number of pages. 1 means that it should be used on the same page it became eligible.

<pre class="propdef">
Name: <dfn id="flow-linger-pgt">flow-linger</dfn>
Values: none | &lt;integer&gt;
Initial: none
Applies To: elements for which 'flow-into' property was specified
Inherited: no
Media: visual
Computed value: as specified
</pre> 



<h3>flow-priority</h3>
<pre class="propdef">
Name: <dfn id="flow-priority-pgt">flow-priority</dfn>
Values: &lt;integer&gt;
Initial: 0
Applies To: 
Inherited: no
Media: visual
Computed value: as specified
</pre> 

<h3>flow-consume</h3>
<pre class="propdef">
Name: <dfn id="flow-consume-pgt">flow-consume</dfn>
Values: some | all
Initial: all for body flow; some for all other flows
Applies To: 
Inherited: no
Media: visual
Computed value: as specified
</pre> 

-->



<h2 class="no-num" id="acknowledgments">
Acknowledgments
</h2>

Tab Atkins, Jr., Brak Kemper, Håkon Wium Lie, Liam Quin, Peter Sorotokin, Alan Stearns