Skip to content

Commit e9eb040

Browse files
rachelandrewrachelandrew
committed
[css-multicol] Tidy up tests and examples after model text update
The examples and tests were now all in the wrong place, after our work on the model. Moved them into better positions.
1 parent 5afdd93 commit e9eb040

File tree

1 file changed

+121
-118
lines changed

1 file changed

+121
-118
lines changed

‎css-multicol-1/Overview.bs

+121-118
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Link Defaults: css-color (property) color, css2 (property) max-height, css-backg
2525
</pre>
2626
<pre class="link-defaults">
2727
spec:css-sizing-3; type:property; text:min-height
28+
spec:css-break-4; type:dfn; text:fragment
2829
</pre>
2930

3031
<style type="text/css">
@@ -146,6 +147,26 @@ Introduction</h2>
146147
an element will be identical to a multi-column layout with only one
147148
column.
148149

150+
<div class="example">
151+
Column gaps (diagonal hatching) and column rules
152+
are shown in this sample rendition of a multi-column container
153+
with padding (cross hatching).
154+
The hatched areas are present for illustrational purposes only.
155+
In actual implementations these areas will be determined by the background,
156+
the second image shows a rendering of a multi-column container with column-rules.
157+
158+
<figure>
159+
<img alt="a diagram showing the various parts of multi-column layout" src="images/initial-example.svg">
160+
<img alt="key to the conventions used to display invisible parts of diagram" src="images/invisible-elements.svg">
161+
<figcaption>A multi-column layout with the non-visible column-span and padding inside the multicol container highlighted.</figcaption>
162+
</figure>
163+
164+
<figure>
165+
<img alt="a diagram showing the various parts of multi-column layout" src="images/initial-example-b.svg">
166+
<figcaption>The same layout as in the first image, as it would be displayed by an implementation.</figcaption>
167+
</figure>
168+
</div>
169+
149170
<h2 id="the-multi-column-model">
150171
The multi-column model</h2>
151172

@@ -154,6 +175,10 @@ The multi-column model</h2>
154175
(or <i>multicol container</i> for short),
155176
and therefore acts as a container for [=multi-column layout=].
156177

178+
<wpt>
179+
multicol-count-computed-004.xht
180+
</wpt>
181+
157182
In the traditional CSS box model,
158183
the content of an element is
159184
flowed into the content box of the corresponding element.
@@ -164,98 +189,85 @@ The multi-column model</h2>
164189
These [=column boxes=] establish
165190
an independent [=block formatting context=]
166191
into which the multi-column container's content flows,
167-
and form the [=containing block=] for its non-positioned childen.
168-
Content overflowing a [=column box=] in the [=block axis=]
169-
[=fragments=] and continues in the next [=column box=].
192+
and form the [=containing block=] for its non-positioned children.
170193

171-
Note: Column boxes, which are [=anonymous boxes=],
172-
do not become the containing block
173-
for [=absolutely-positioned boxes=].
174-
The 'position' property, which establishes a containing block for such boxes,
175-
applies to the [=multicol container=], it being the [=principal box=].
176-
177-
The column boxes are ordered
178-
in the [=inline base direction=] of the multicol container
179-
and arranged into <dfn lt="multi-column line | multi-col line">multicol lines</dfn>.
180-
The <dfn export>column width</dfn> is the length of the column box in the inline direction.
181-
The <dfn export>column height</dfn> is the length of the column box in the block direction.
182-
All column boxes in a line have the same column width,
183-
and all column boxes in a line have the same column height.
194+
<div class=example>
195+
In this example, the width of the image is set with these rules:
184196

185-
Within each [=multi-col line=] in the multi-column container,
186-
adjacent column boxes are separated by a <dfn noexport>column gap</dfn>,
187-
which may contain a <dfn noexport>column rule</dfn>.
188-
All column gaps in the same multi-column container are equal.
189-
All column rules in the same multi-column container are also equal, if they appear;
190-
column rules only appear between columns that both have content.
197+
<pre highlight="css">
198+
img {
199+
display: block;
200+
width: 100%;
201+
}
202+
</pre>
191203

192-
In the simplest case a multicol container will contain only one line
193-
of columns, and the height of each column will be equivalent to the
194-
used height of the multi-column container's content box.
195-
However, [=fragmentation=] or [=spanners=]
196-
can split the content of the [=multi-column container=]
197-
into multiple [=multi-col lines=].
204+
Given that the column box creates a new [=block formatting context=],
205+
the 'width' is calculated relative to the column box.
206+
Therefore the image will not overflow the column box:
198207

199-
If the multi-column container is paginated, the height of each column is
200-
constrained by the page and the content continues in a new line of
201-
column boxes on the next page; a column box never splits across pages.
208+
<figure>
209+
<img src="images/image-inside-column.svg" alt="an image contained inside a column box">
210+
<figcaption>The image is constrained by the column box that it is displayed in.</figcaption>
211+
</figure>
212+
</div>
202213

203-
The same effect occurs when a <i>spanning element</i> divides the
204-
multi-column container: the columns before the spanning element are
205-
balanced and shortened to fit their content. Content after the
206-
spanning element then flows into a new, subsequent line of column boxes.
214+
<div class="example">
215+
Given that the column box creates a new [=block formatting context=], a top margin set on the first child element of a multicol container will not collapse with the margins of the multicol container.
207216

208-
A [=multi-column container=] therefore is a regular [=block container=]
209-
that establishes a new [=independent formatting context=]
210-
whose contents consist of a series of
211-
[=multi-col lines=] and [=multi-col spanners=].
212-
Each [=multi-column line=] acts as a [=block-level box=]
213-
that establishes a [=multi-column formatting context=]
214-
for its [=column boxes=];
215-
and each [=spanner=] acts as a [=block-level box=]
216-
that establishes an [=independent formatting context=]
217-
with its type depending on its 'display' value as usual.
217+
<figure>
218+
<img src="images/margins-do-not-collapse.svg" alt="The first paragraph has a margin-top of 1em, which appears before the text.">
219+
<figcaption>The margin above the first paragraph has not collapsed, leaving a 1em margin above the first line in the multicol container.</figcaption>
220+
</figure>
221+
</div>
218222

219223
<wpt>
220-
multicol-count-computed-004.xht
224+
multicol-margin-001.xht
225+
multicol-margin-002.xht
226+
multicol-margin-child-001.xht
227+
multicol-nested-margin-001.xht
228+
multicol-nested-margin-002.xht
229+
multicol-nested-margin-003.xht
230+
multicol-nested-margin-004.xht
231+
multicol-nested-margin-005.xht
221232
</wpt>
222233

234+
Floats that appear inside multi-column layouts are positioned with
235+
regard to the [=column box=] where the float appears.
223236

224237
<div class="example">
225-
Column gaps (diagonal hatching) and column rules are shown in this
226-
sample rendition of a multi-column container with padding (cross hatching). The
227-
hatched areas are present for illustrational purposes only. In actual
228-
implementations these areas will be determined by the background, the second image shows a rendering of a multi-column container with column-rules.
238+
In this example, this CSS fragment describes the presentation of the image:
229239

230-
<figure>
231-
<img alt="a diagram showing the various parts of multi-column layout" src="images/initial-example.svg">
232-
<img alt="key to the conventions used to display invisible parts of diagram" src="images/invisible-elements.svg">
233-
<figcaption>A multi-column layout with the non-visible column-span and padding inside the multicol container highlighted.</figcaption>
234-
</figure>
240+
<pre highlight="css">
241+
img {
242+
display: block;
243+
float: right;
244+
}
245+
</pre>
235246

236-
247+
In the HTML, the image appears after the sentence ending, "the leg of a chicken".
237248

238249
<figure>
239-
<img alt="a diagram showing the various parts of multi-column layout" src="images/initial-example-b.svg">
240-
<figcaption>The same layout as in the first image, as it would be displayed by an implementation.</figcaption>
250+
<img src="images/image-floated-in-column.svg" alt="an image floated and contained inside a column box">
251+
<figcaption>The image is floated inside the column box it appears in.</figcaption>
241252
</figure>
242253
</div>
243254

244-
<div class="example">
245-
<figure>
246-
<img alt="a diagram showing a spanning element causing the shortened columns above the element with text continuing in new columns below" src="images/simple-span-example.svg">
247-
<figcaption>A demonstration of how the spanning element divides the multicol container.</figcaption>
248-
</figure>
249-
</div>
255+
Content overflowing a [=column box=] in the [=block axis=]
256+
[=fragments=] and continues in the next [=column box=].
250257

258+
Note: Column boxes, which are [=anonymous boxes=],
259+
do not become the containing block
260+
for [=absolutely-positioned boxes=].
261+
The 'position' property, which establishes a containing block for such boxes,
262+
applies to the [=multicol container=], it being the [=principal box=].
251263

252264
<wpt>
253265
multicol-containing-001.xht
254266
multicol-containing-002.xht
255267
</wpt>
256268

257269
<div class="example">
258-
In this example, the multi-column container has ''position: relative'' thus becoming the containing block. The image is a direct child of the multi-column container and has ''position: absolute''. It takes positioning from the multi-column container and not from the column box.
270+
In this example, the [=multi-column container=] has ''position: relative'' thus becoming the containing block. The image is a direct child of the [=multi-column container=] and has ''position: absolute''. It takes positioning from the [=multi-column container=] and not from the [=column box=].
259271

260272
<pre highlight="css">
261273
.container {
@@ -270,70 +282,59 @@ The multi-column model</h2>
270282
</pre>
271283

272284
<figure>
273-
<img src="images/column-not-containing-block.svg" alt="The absolutely positioned image is positioned by reference to the multicol container not the column box.">
285+
<img src="images/column-not-containing-block.svg" alt="The absolutely positioned image is positioned by reference to the [=multi-column container=] not the [=column box=].">
274286
<figcaption>The figure demonstrates that the absolutely positioned image is positioned by reference to the multicol container and not the column box.</figcaption>
275287
</figure>
276288
</div>
277289

278-
<div class=example>
279-
In this example, the width of the image is set with these rules:
280-
281-
<pre highlight="css">
282-
img { display: block; width: 100% }
283-
</pre>
284-
285-
Given that the width is calculated relative to the column box, the
286-
image will be as wide as the column box:
287-
288-
<figure>
289-
<img src="images/image-inside-column.svg" alt="an image contained inside a column box">
290-
<figcaption>The image is constrained by the column box that it is displayed in.</figcaption>
291-
</figure>
292-
</div>
293-
294-
Floats that appear inside multi-column layouts are positioned with
295-
regard to the column box where the float appears.
296-
297-
<div class="example">
298-
In this example, this CSS fragment describes the presentation of the image:
290+
The column boxes are ordered
291+
in the [=inline base direction=] of the multicol container
292+
and arranged into <dfn lt="multi-column line | multi-col line | multicol line">multicol lines</dfn>.
293+
The <dfn export>column width</dfn> is the length of the column box in the inline direction.
294+
The <dfn export>column height</dfn> is the length of the column box in the block direction.
295+
All column boxes in a line have the same column width,
296+
and all column boxes in a line have the same column height.
299297

300-
<pre highlight="css">
301-
img {
302-
display: block;
303-
float: right
304-
}
305-
</pre>
298+
Within each [=multicol line=] in the multi-column container,
299+
adjacent column boxes are separated by a <dfn noexport>column gap</dfn>,
300+
which may contain a <dfn noexport>column rule</dfn>.
301+
All column gaps in the same multi-column container are equal.
302+
All column rules in the same multi-column container are also equal, if they appear;
303+
column rules only appear between columns that both have content.
306304

307-
In the HTML, the image appears after the sentence ending, "the leg of a chicken".
305+
In the simplest case a multicol container will contain only one line
306+
of columns, and the height of each column will be equivalent to the
307+
used height of the multi-column container's content box.
308+
However, [=fragmentation=] or [=spanners=]
309+
can split the content of the [=multi-column container=]
310+
into multiple [=multicol lines=].
308311

309-
<figure>
310-
<img src="images/image-floated-in-column.svg" alt="an image floated and contained inside a column box">
311-
<figcaption>The image is floated inside the column box it appears in.</figcaption>
312-
</figure>
313-
</div>
312+
If the multi-column container is paginated, the height of each column is
313+
constrained by the page and the content continues in a new line of
314+
column boxes on the next page; a column box never splits across pages.
314315

315-
A multi-column container establishes a new block formatting context,
316-
as per CSS 2.1 section 9.4.1.
316+
The same effect occurs when a <i>spanning element</i> divides the
317+
multi-column container: the columns before the spanning element are
318+
balanced and shortened to fit their content. Content after the
319+
spanning element then flows into a new, subsequent line of column boxes.
317320

318321
<div class="example">
319-
A top margin set on the first child element of a multicol container will not collapse with the margins of the multicol container.
320-
321322
<figure>
322-
<img src="images/margins-do-not-collapse.svg" alt="The first paragraph has a margin-top of 1em, which appears before the text.">
323-
<figcaption>The margin above the first paragraph has not collapsed, leaving a 1em margin above the first line in the multicol container.</figcaption>
323+
<img alt="a diagram showing a spanning element causing the shortened columns above the element with text continuing in new columns below" src="images/simple-span-example.svg">
324+
<figcaption>A demonstration of how the spanning element divides the multicol container.</figcaption>
324325
</figure>
325326
</div>
326327

327-
<wpt>
328-
multicol-margin-001.xht
329-
multicol-margin-002.xht
330-
multicol-margin-child-001.xht
331-
multicol-nested-margin-001.xht
332-
multicol-nested-margin-002.xht
333-
multicol-nested-margin-003.xht
334-
multicol-nested-margin-004.xht
335-
multicol-nested-margin-005.xht
336-
</wpt>
328+
A [=multi-column container=] therefore is a regular [=block container=]
329+
that establishes a new [=independent formatting context=]
330+
whose contents consist of a series of
331+
[=multicol lines=] and <dfn:export>multicol spanners</dfn>.
332+
Each [=multi-column line=] acts as a [=block-level box=]
333+
that establishes a <dfn:export>multi-column formatting context</dfn>
334+
for its [=column boxes=];
335+
and each [=spanner=] acts as a [=block-level box=]
336+
that establishes an [=independent formatting context=]
337+
with its type depending on its 'display' value as usual.
337338

338339
Nested multi-column containers are allowed, but there may be
339340
implementation-specific limits.
@@ -952,9 +953,9 @@ Spanning columns</h2>
952953
The element spans across all columns of the nearest multicol
953954
ancestor in the same block formatting context.
954955
Content in the normal flow that appears before the
955-
element is automatically balanced across all columns in the immediately preceding column row before the
956-
element appears.
957-
The element establishes an independent <a>formatting context</a>.
956+
element is automatically balanced across all columns
957+
in the immediately preceding multi-column line before the element appears.
958+
The element establishes an [=independent formatting context=].
958959

959960
Note: Whether the element establishes a new <a>formatting context</a>
960961
does not depend on whether the element is a descendent of a multicol or not.
@@ -1433,6 +1434,7 @@ This appendix is <em>informative</em>.
14331434

14341435
<h3 id="changes-from-20180528">Changes from the <a href="https://www.w3.org/TR/2018/WD-css-multicol-1-20180528/">Working Draft (WD) of 28 May 2018</a></h3>
14351436
<ul>
1437+
<li>Reworded the section <a href="#the-multi-column-model">The multi-column model</a>, based on input from Morten Stenshorne in <a href="https://github.com/w3c/csswg-drafts/issues/2203#issuecomment-431695940">issue 2203</a>.</li>
14361438
<li>Removed the at-risk marker from the length-percentage value for 'column-gap'. <a href="https://github.com/w3c/csswg-drafts/issues/3988">Resolved 4 June 2019.</a></li>
14371439
<li>Added the paragraph "In continuous contexts, this property will only be consulted if the length of columns has been constrained in the block dimension, including min and max constraints (e.g., 'height', 'min-height', 'max-height'). Otherwise, columns will automatically be balanced." This paragraph (without the additional detail regarding min and max constraints) was commented out in 2012, causing an interoperability issue. Also corrected the example of content ending up all in the first column, by adding the height constraint. Resolved <a href="https://github.com/w3c/csswg-drafts/issues/3224#issuecomment-468089503">28 February 2019</a></li>
14381440
<li>Updated the introduction to remove mention of the benefits of multicol over using tables for layout and instead refer to the unique characteristics of multicol. Editorial change referenced in <a href="https://github.com/w3c/csswg-drafts/issues/3654">issue 3654</a>.</li>
@@ -1510,6 +1512,7 @@ Acknowledgments</h2>
15101512
Markus Mielke,
15111513
Melinda Grant,
15121514
Michael Day,
1515+
Morten Stenshorne,
15131516
Øyvind Stenhaug,
15141517
Peter Linss,
15151518
Peter-Paul Koch,

0 commit comments

Comments
 (0)