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="flow-policy-heading">Copying a flow: the 'flow-policy' 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]] only allows for an element to be moved to a ''named flow'', so we add the 'flow-policy' property to allow the same element to serve two roles.

<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="flow-policy-property">flow-policy</dfn>
Value: extract | copy
Initial: extract
Applies To: all elements with a value of 'flow-into' other than none.
Inherited: no
Media: visual
Computed value: as specified
</pre> 

<dl>

<dt>extract</dt>
<dd>the element is taken out of its parent’s flow and placed into the named flow set by the value of the 'flow-into' property.</dd>

<dt>copy</dt>

<dd>the element remains into it's normal parent's flow but a copy of the element is also extracted from there and placed into the named flow set by the value of the 'flow-into' property.</dd>

</dl>

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

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


<h3 id="flow-persist-heading">Making “sticky” headers: the 'flow-persist' property</h3>

An element flowed into a running head should appear on every page until the value of the element changes, at which point the new value should be used. We define the 'flow-persist' property to control how content is rendered in region chains (????).


We also need to specify which element is used in a running head, when there are multiple possibilities. [[CSS3GCPM]] defines start, first, last, and first-except values. 












<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> 

<dl>

<dt>normal</dt>
<dd>Content from the named flow is rendered as described in [[CSS3-REGIONS]].</dd>

<dt>persist</dt>

<dd>Eligible content from the named flow is placed into the first box of the region chain as usual. If there is no eligible content on subsequent pages, the last-used content is used in the region box until new eligible content appears. 

</dd>

<p class="issue">“That is not what I meant at all; That is not it, at all.”   —T.S. Eliot</p>





<dt>static</dt>

<dd>The first instance of the element is used in every region associated with the region chain (this is the equivalent of flow-options: static in [[PGT]]).</dd>

</dl>

<p class="issue">Above definitions need work</p>

<dl>

<dt>first</dt>
<dd>The value of the first assignment on the page is used. If there is no assignment on the page, the entry value is used. first is the default value.</dd>

<dt>start</dt>

<dd>If the element is the first element on the page, the value of the first assignment is used. Otherwise the entry value is used. The entry value may be empty if the element hasn’t yet appeared. </dd>

<dt>last</dt>

<dd>The exit value is used.</dd>

<dt>first-except</dt>

<dd>This is identical to first, except that the empty string is used on the page where the value is assigned.</dd>

</dl>



<div class="example">

<pre>
h1 { 
  flow-into: chapter-title element; 
  flow-policy: copy;
}

@page {
  @top-center {
    flow-from: chapter-title;
    flow-persist: persist start;
    }
}

</pre>

The @top-center margin box will be populated with the content of the <code>h1</code>. The <code>h1</code> will also appear in the document in its normal place.
</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., Håkon Wium Lie, Liam Quin, Peter Sorotokin, Alan Stearns