- From: Alan Stearns via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 02 Mar 2012 22:52:48 +0000
- To: public-css-commits@w3.org
Update of /sources/public/csswg/css3-page-template In directory hutz:/tmp/cvs-serv6109/css3-page-template Modified Files: Overview.src.html Log Message: added pictures to some examples and revised some text Index: Overview.src.html =================================================================== RCS file: /sources/public/csswg/css3-page-template/Overview.src.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- Overview.src.html 29 Feb 2012 01:25:48 -0000 1.3 +++ Overview.src.html 2 Mar 2012 22:52:46 -0000 1.4 @@ -4,27 +4,14 @@ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>CSS Pagination Templates Module Level 3</title> <link rel="stylesheet" type="text/css" href="../default.css"> - <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-[STATUS]"> + <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css"> <link id="st" href="../alternate-spec-style.css" rel="stylesheet" type="text/css" title="alternate spec style"> <style type="text/css"> - /* delete this block when you've cleared out all the .replaceme elements */ - .replaceme { - border: solid red; - padding: 0 0.5em; - margin: 0 0.1em; - background: yellow; - color: green; - } - .replaceme:before { - content: "FIXME("; - color: black; - } - .replaceme:after { - content: ")"; - color: black; + .separate-pre { + --margin: 5%; + background-color: rgba(0, 0, 0, 0.08); } - </style> </head> @@ -65,16 +52,11 @@ <h2 class="no-num no-toc" id="abstract">Abstract</h2> - <p>CSS is a language for describing the rendering of structured documents - (such as HTML and XML) on screen, on paper, in speech, etc. This module - contains the features of CSS level 3 relating to pagination templates. - It includes and extends the functionality of CSS level 2 [[!CSS21]], - which builds on CSS level 1 [[CSS1]]. - The main extension compared to level 2 is the ability to specify one or more pagination templates that be used to render content. + <p>The Pagination Templates module describes templates that can be defined in CSS to display content in a paginated view. These templates define a page containing one or more boxes with content assignments. As content overflows additional pages are generated using template selection rules until all of the content is displayed. <h2 class="no-num no-toc" id="status">Status of this document</h2> -<p style="color:red"><strong>This document is a proposal that will need a few iterations before becoming an Editor's Draft. It has not yet been adopted by the Working Group, and should not be considered to be part of CSS.</strong></p> +<p><strong>This document is only an Editor's Draft. It has not yet been adopted by the Working Group, and should not be considered to be part of CSS.</strong></p> <p>The following features are at risk: none @@ -89,6 +71,8 @@ <p>This module describes how to define pagination templates in CSS. In CSS 2.1 content displayed on-screen is assumed to be a single continuous canvas. Pagination templates provide a mechanism for a 'paginated' experience that applies to on-screen presentation as well as printed media. Pagination templates describe the layout of pages in which content is displayed as the user moves from page to page on screen or prints the document content. When content is laid out using pagination templates, pages are generated as needed to accommodate all the content. + <p class="issue">The draft as it stands requires pagination to present the repeated template layouts. Other methods of repeating template layouts to accommodate content might be specified, but the draft would need to be reviewed to remove all reliances on paged displays. + <p>Pagination templates consist of anonymous boxes called slots created by CSS to contain content. Layouts that use pagination templates mainly determine the size of these slots from the template definition instead of the intrinsic size of their content. When content does not fit into a template slot, additional pages are created with more slots to contain the overflow content. <p>Multiple pagination templates can be defined for a given document. A paginated element can use a single template or select from a set of templates each time a new page needs to be generated. Which template is used for a given page can be defined by a selector or by choosing a template based on available content. Elements can further constrain the applicable template set by listing a subset of templates that apply. @@ -107,7 +91,7 @@ <p>An @template rule defines a pagination template. Pagination templates contain one or more slots to display content. An element can use pagination templates if its 'overflow-style' property is set to any of the paged-* values defined in css3-gcpm. If a document defines no pagination templates, then there is an implicit paginated template with a single slot containing the paginated element's contents. - <p class="issue">Do pagination templates get their size from the element with the overflow-style property, or can their size be set in the @template rule? Can we use a default 100%/100% size? + <p class="issue">Do pagination templates get their size (and other characteristics) from the element with the overflow-style property, or does this have be set in the @template rule? Can templates use a default 100%/100% size based on the element's box? <p>A slot is an anonymous box in a paginated template where content can be placed. In an @template rule @slot rules create slots. The order of @slot rules determines the order of the boxes in the paginated template. Each @slot rule can take an optional name. @@ -124,7 +108,7 @@ </pre> </div> - <p>If any slot in a particular page has overflow content, a new page is created with a new set of slots to receive the overflow content. Slots with the same named flow assignment form a region chain (within a pagination template and/or across pages created from pagination templates). When a new page is created a slot assigned element content or content from a named flow may not have any content left to render. In this case the slot for the exhausted content source is not instantiated. + <p>If any slot in a particular page has overflow content, a new page is created with a new set of slots to receive the overflow content. Slots with the same named flow assignment form a region chain (within a pagination template and/or across pages created from pagination templates). When a new page is created a slot that has been assigned element content or content from a named flow may not have any content left to render. In this case the slot for the exhausted content source is not instantiated. <p class="issue">If there is more than one slot with no 'content' or 'flow-from' assignment, does the element's content use all of these slots like a region chain, or is only the last unassigned slot used for content? @@ -133,26 +117,19 @@ <p>The three examples below are equivalent, but merely illustrate how content from the element can be assigned to paginated template slots. Actual use of templates would either define more slots or assign content differently than the default. - <hr> - <pre> - body { overflow-style: paged-x; } - </pre> - <hr> - <pre> + <pre class='separate-pre'> + body { overflow-style: paged-x; }</pre> + <pre class='separate-pre'> body { overflow-style: paged-x; } @template { @slot { } - } - </pre> - <hr> - <pre> + }</pre> + <pre class='separate-pre'> body { overflow-style: paged-x; } body > * { flow-into: body-flow; } @template { @slot { flow-from: body-flow; } - } - <hr> - </pre> + }</pre> </div> <p class="issue">@slot rules are a first pass at defining CSS-created boxes. Other means of creating and addressing pseudo-element slots have been discussed on www-style. Another possibility is using HTML like WebComponents does to define the boxes. However the boxes are created there needs to be a way of assigning content to boxes and accessing the template structure through scripting. If pseudo-elements are used, then OM for pseudo-elements must be defined. If HTML templates are used a declarative method of mapping content to elements must be defined. @@ -163,6 +140,12 @@ <div class='example'> <p>A paginated template could contain two side-by-side slots that paginate two separate articles. Side-by-side translations are often laid out this way. This example fills the left side of the paged view with content from an English article and the right side with content from a French article. New pages and slots are created until the content from both articles is exhausted. If one article is longer than the other then in this simple example template the longer article will continue taking up just its half of the page. + <p> + <img src="images/side-by-side-1.png" width="120" alt="side-by-side flows on a page"> + <span style="font-size:50px">…</span> + <img src="images/side-by-side-2.png" width="120" alt="side-by-side flows with the left ending"> + <img src="images/only-one-side-3.png" width="120" alt="only the right flow"> + <span style="font-size:50px">…</span> <pre> body { overflow-style: paged-x; } .english { flow-into: english-flow; } @@ -171,12 +154,14 @@ @slot left { flow-from: english-flow; width: 40%; + height: 90%; padding: 5%; float: left; } @slot right { flow-from: french-flow; width: 40%; + height: 90%; padding: 5% float: right; } @@ -190,6 +175,12 @@ <div class='example'> <p>The example above could position the slots using grid layout rather than floats. In this simple example the longer article will take up the entire page once the shorter article is exhausted. + <p> + <img src="images/side-by-side-1.png" width="120" alt="side-by-side flows on a page"> + <span style="font-size:50px">…</span> + <img src="images/side-by-side-2.png" width="120" alt="side-by-side flows with the left ending"> + <img src="images/whole-page.png" width="120" alt="the right flow takes up the whole page"> + <span style="font-size:50px">…</span> <pre> body { overflow-style: paged-x; } .english { flow-into: english-flow; } @@ -238,12 +229,13 @@ </pre> </div> - <p class="issue">Instead of specifying a template-set, should there be a way of scoping @template rules to an element? The reason not to is to be able to re-use pagination templates with multiple elements. + <p class="issue">Instead of specifying a template-set, should there be a way of scoping @template rules to an element? The reason to put them on the document is to re-use pagination templates with multiple elements. + <p class="issue">One way of promoting re-use of paginated templates would be to parameterize the named flow idents. Instead of using named flow idents directly, @slot rules could use a parameter and a paginated element using the template would pass in the particular named flow ident meant for that parameter. <h3 id='ordered-templates'> Selecting Templates by Page Order</h3> - <p>Selectors such as :first can be used on a paginated template to define a separate template for pages that match the selector. + <p>Selectors such as :first can be used on a pagination template to define a separate template for pages that match the selector. <p class="issue">Should we use :left and :right and allow viewing more than one page at a time in a viewport? Should we have :nth(x) selectors? @@ -266,14 +258,23 @@ </pre> </div> -<h3 id='selection-from-available-content'> + <p class="issue">Depending on how template selection is defined, there will likely be scenarios where degenerate template sets can either fail to display all of the content or result in an infinite loop of page generation. This first draft falls into the latter category (make a :first template with a slot that overflows, but fail to include an assignment for that slot's content in all other templates), so this will need to be addressed with more selection rules. + +<h3 id='selection-from-required-flows'> Selecting Templates from Required Flows</h3> - <p>The 'required-flow' property can be used in a paginated template to list named flows that must still have content in order for the template to be used. If more than one template has a 'required-flow' value that matches the remaining flow content, the first template that matches will be used. + <p>The 'required-flow' property can be used in a pagination template to list named flows that must still have content in order for the template to be used. If more than one template has a 'required-flow' value that matches the remaining flow content, the first template that matches will be used. <div class='example'> <p>"Continued on" layout. - <p>Using the same two-article markup as in previous examples, these pagination templates will display an inital page with the beginning of both articles. If the lead story has more content than will fit on that first page, the next pages will show only content from that lead story. When the content from the lead story is consumed, then pages will follow with content from the related article. + <p>These pagination templates will display an inital page with the beginning of both the 'lead-story' flow and a 'related-article' flow. If the lead story has more content than will fit on that first page, the next page(s) will show only content from that lead story. When the content from the lead story is exhausted, then pages will follow with content from the related article. + <p> + <img src="images/side-by-side-1.png" width="120" alt="side-by-side flows on a page"> + <img src="images/first-article-columns.png" width="120" alt="columns continuing just the first flow"> + <span style="font-size:50px">…</span> + <img src="images/first-article-end.png" width="120" alt="columns ending the first flow"> + <img src="images/second-article-columns.png" width="120" alt="columns continuing the second flow"> + <span style="font-size:50px">…</span> <pre> body { overflow-style: paged-x; } .lead-story { flow-into: first-flow; } @@ -282,12 +283,14 @@ @slot left { flow-from: first-flow; width: 40%; + height: 90%; padding: 5%; float: left; } @slot right { flow-from: second-flow; width: 40%; + height: 90%; padding: 5% float: left; } @@ -318,15 +321,17 @@ <p>Pagination templates can be selected based on the order of content in the original markup. Content may be split out into one or more named flows, but the original order can be discovered in the markup. - <p>Pagination templates have a 'primary' content flow. The primary content for a pagination template is usually the content of the paginated element. If no slot displays the element contents, then the primary content of the paginated template is the first named flow in its required-flow declaration. + <p>Pagination templates have a 'primary' content flow. The primary content for a pagination template is usually the content of the paginated element. If no slot displays the element contents, then the primary content of the pagination template is the first named flow in its required-flow declaration. <p>When selecting the pagination template for the next page, the primary content flow in the original markup can be scanned to determine whether any out-of-flow content in named flows was originally related to the next page of primary flow. If this is the case, then those named flows have 'available' content for the purpose of selecting an appropriate template that can display this content. - <p>Pagination templates can have an 'available-flow' declaration listing the named flows that must have available content relative to the pagination template's primary flow. + <p>Pagination templates can have an 'available-flow' declaration listing the named flows that must have available content for the template to be selected. If a template with an 'available-flow' declaration is chosen, only the available content in those flows is displayed in the slots associated with those flows. - <p class="issue">Expand this. + <div class='example'> + <p>Consider an article element that contains images scattered throughout. Assign the images to a flow named 'images' and the rest of the article to a flow named 'text'. Then define two pagination templates - one that has slots only for the 'text' flow, and another that has slots for both the 'text' and 'images' flows. Both templates require the 'text' flow, but the second template also requires the 'images' flow and has an 'available-flow' declaration listing the 'images' flow. Each time a page is laid out, the original article element is scanned to see whether an image element is in the next page's worth of content (determined by some heuristic, not layout). If so, then that content from the 'images' flow is available for the purpose of selecting a template. + </div> - <p class="issue">IDPF has a notion of 'available' content. For example, consider a content source that contains a single article with images scattered throughout. Assign the images to a flow named 'images' and the rest of the article to a flow named 'text'. Then define two pagination templates - one that has slots only for the text flow, and another that has slots for both the text and images flows. Each time a page is laid out, the original article is scanned to see whether an image element would have shown up on the page. If so, then that content from the 'images' flow is available for the purpose of selecting a template. + <p class="issue">Expand this. <div class='example'> <p>Assume you have an article that contains both pull quotes and images. If only images <em>or</em> pull quotes would occur on a page, position those elements in the center right of the template. But if both images <em>and</em> pull quotes would appear, position the images in the top left and the pull quotes in the bottom right. @@ -336,183 +341,30 @@ <h2 id="cssom"> CSS Object Model Modifications</h2> - <p class='issue'>There should be extensive OM defined to access pages and slots. What page is being displayed should be available. Templates, pages and slots should be able to accept event handlers. Anchors should navigate to the appropriate page (as should search). What content fits in each slot and page should be accessible. Lots to fill out here. + <p class='issue'>There should be extensive OM defined to access pages and slots. What page is being displayed should be available. Pages and slots should accept event handlers. Anchors should navigate to the appropriate page (as should search). What content fits in each slot and page should be determinable. Lots to fill out here. <h2 id="conformance"> Conformance</h2> -<h3 id="conventions"> -Document Conventions</h3> - - <p>Conformance requirements are expressed with a combination of - descriptive assertions and RFC 2119 terminology. The key words “MUST”, - “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, - “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this - document are to be interpreted as described in RFC 2119. - However, for readability, these words do not appear in all uppercase - letters in this specification. - - <p>All of the text of this specification is normative except sections - explicitly marked as non-normative, examples, and notes. [[!RFC2119]]</p> - - <p>Examples in this specification are introduced with the words “for example” - or are set apart from the normative text with <code>class="example"</code>, - like this: - - <div class="example"> - <p>This is an example of an informative example.</p> - </div> - - <p>Informative notes begin with the word “Note” and are set apart from the - normative text with <code>class="note"</code>, like this: - - <p class="note">Note, this is an informative note.</p> - -<h3 id="conformance-classes"> -Conformance Classes</h3> - - <p>Conformance to <var class="replaceme">CSS TEMPLATE Module</var> - is defined for three conformance classes: - <dl> - <dt><dfn title="style sheet!!as conformance class">style sheet</dfn> - </dt><dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS - style sheet</a>. - </dd><dt><dfn>renderer</dfn></dt> - <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> - that interprets the semantics of a style sheet and renders - documents that use them. - </dd><dt><dfn id="authoring-tool">authoring tool</dfn></dt> - <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> - that writes a style sheet. - </dd></dl> - - <p>A style sheet is conformant to <var class="replaceme">CSS TEMPLATE Module</var> - if all of its declarations that use properties defined in this module - have values that are valid according to the generic CSS grammar and the - individual grammars of each property as given in this module. - - <p>A renderer is conformant to <var class="replaceme">CSS TEMPLATE Module</var> - if, in addition to interpreting the style sheet as defined by the - appropriate specifications, it supports all the features defined - by <var class="replaceme">CSS TEMPLATE Module</var> by parsing them correctly - and rendering the document accordingly. However, the inability of a - UA to correctly render a document due to limitations of the device - does not make the UA non-conformant. (For example, a UA is not - required to render color on a monochrome monitor.) - - <p>An authoring tool is conformant to <var class="replaceme">CSS TEMPLATE Module</var> - if it writes style sheets that are syntactically correct according to the - generic CSS grammar and the individual grammars of each feature in - this module, and meet all other conformance requirements of style sheets - as described in this module. - -<h3 id="partial"> -Partial Implementations</h3> - - <p>So that authors can exploit the forward-compatible parsing rules to - assign fallback values, CSS renderers <strong>must</strong> - treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore - as appropriate</a>) any at-rules, properties, property values, keywords, - and other syntactic constructs for which they have no usable level of - support. In particular, user agents <strong>must not</strong> selectively - ignore unsupported component values and honor supported values in a single - multi-value property declaration: if any value is considered invalid - (as unsupported values must be), CSS requires that the entire declaration - be ignored.</p> - -<h3 id="experimental"> -Experimental Implementations</h3> - - <p>To avoid clashes with future CSS features, the CSS2.1 specification - reserves a <a href="http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords">prefixed - syntax</a> for proprietary and experimental extensions to CSS. - - <p>Prior to a specification reaching the Candidate Recommendation stage - in the W3C process, all implementations of a CSS feature are considered - experimental. The CSS Working Group recommends that implementations - use a vendor-prefixed syntax for such features, including those in - W3C Working Drafts. This avoids incompatibilities with future changes - in the draft. - </p> - -<h3 id="testing">Non-Experimental Implementations</h3> - - <p>Once a specification reaches the Candidate Recommendation stage, - non-experimental implementations are possible, and implementors should - release an unprefixed implementation of any CR-level feature they - can demonstrate to be correctly implemented according to spec. - - <p>To establish and maintain the interoperability of CSS across - implementations, the CSS Working Group requests that non-experimental - CSS renderers submit an implementation report (and, if necessary, the - testcases used for that implementation report) to the W3C before - releasing an unprefixed implementation of any CSS features. Testcases - submitted to W3C are subject to review and correction by the CSS - Working Group. - - <p>Further information on submitting testcases and implementation reports - can be found from on the CSS Working Group's website at - <a href="http://www.w3.org/Style/CSS/Test/">http://www.w3.org/Style/CSS/Test/</a>. - Questions should be directed to the - <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">public-css-testsuite@w3.org</a> - mailing list. - -<h3 id="cr-exit-criteria"> -CR Exit Criteria</h3> - - <p class="issue">[Change or remove the following CR exit criteria if - the spec is not a module, but, e.g., a Note or a profile. This text was <a href="http://www.w3.org/Style/CSS/Tracker/actions/44"> decided on 2008-06-04.</a>]</p> - - <p> - For this specification to be advanced to Proposed Recommendation, - there must be at least two independent, interoperable implementations - of each feature. Each feature may be implemented by a different set of - products, there is no requirement that all features be implemented by - a single product. For the purposes of this criterion, we define the - following terms: - - <dl> - <dt>independent </dt><dd>each implementation must be developed by a - different party and cannot share, reuse, or derive from code - used by another qualifying implementation. Sections of code that - have no bearing on the implementation of this specification are - exempt from this requirement. - - </dd><dt>interoperable </dt><dd>passing the respective test case(s) in the - official CSS test suite, or, if the implementation is not a Web - browser, an equivalent test. Every relevant test in the test - suite should have an equivalent test created if such a user - agent (UA) is to be used to claim interoperability. In addition - if such a UA is to be used to claim interoperability, then there - must one or more additional UAs which can also pass those - equivalent tests in the same way for the purpose of - interoperability. The equivalent tests must be made publicly - available for the purposes of peer review. - - </dd><dt>implementation </dt><dd>a user agent which: - - <ol class="inline"> - <li>implements the specification. - - </li><li>is available to the general public. The implementation may - be a shipping product or other publicly available version - (i.e., beta version, preview release, or “nightly build”). - Non-shipping product releases must have implemented the - feature(s) for a period of at least one month in order to - demonstrate stability. - - </li><li>is not experimental (i.e., a version specifically designed - to pass the test suite and is not intended for normal usage - going forward). - </li></ol> - </dd></dl> - - <p>The specification will remain Candidate Recommendation for at least - six months. - <h2 class="no-num" id="acknowledgments">Acknowledgments</h2> - <p><var class="replaceme">[acknowledgments]</var></p> + <p>The editor is grateful to the CSS working group for their feedback and help with the genesis of this specification.</p> + + <p>In addition, the editor would like to thank the following individuals for their contributions, either during the conception of CSS Pagination Templates or during its development and specification review process:</p> + <ul> + <li>Rossen Atanassov</li> + <li>Tab Atkins</li> + <li>Alexandru Chiculita</li> + <li>Sylvain Galineau</li> + <li>Vincent Hardy</li> + <li>David Hyatt</li> + <li>Brad Kemper</li> + <li>Håkon Wium Lie</li> + <li>Alex Mogilevsky</li> + <li>Christoph Päper</li> + <li>Peter Sorotokin</li> + <li>Stephen Zilles</li> + </ul> <h2 class="no-num" id="references">References</h2>
Received on Friday, 2 March 2012 22:52:51 UTC