[css-ruby] Add ASCII art diagrams to illustrate section 3.1.1

Author: frivoal

css-ruby-1/Overview.bs

@@ -787,6 +787,121 @@ Inline-axis Interlinear Layout</h4>
 	when its content is narrower than the measure of the box
 	is specified by its 'ruby-align' property.
 
+	<div class=example>
+		The following diagrams illustrate these rules,
+		covering typical situations
+		as well as a few more complex ones.
+		In each case,
+		[=base boxes=] and [=annotation boxes=] are assumed to have ''ruby-align: center'',
+		while <!--[=base containers=] and --> [=annotation containers=] are assumed to have ''ruby-align: space-between''.
+
+		Red brackets (<span style=color:red>[ ]</span>) represent [=base boxes=],
+		blue brackets (<span style=color:blue>[ ]</span>) represent [=annotation boxes=],
+		and gray bars (<span style=color:gray>|</span>) represent the limits of [=ruby columns=].
+		[=Ruby containers=], [=base containers=], and [=annotation containers=] are omitted.
+
+		<dl>
+			<dt id=ex-separate>Separate / non spanning:
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>  a1  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>  a2  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>annotation-3<span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span>base 1<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>base 2<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>   base 3   <span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				Boxes within each [=column=] are sized to match the widest box of that [=column=].
+				The value of 'ruby-align' on each [=base box=] and [=annotation box=] is used
+				to distribute the extra space in each box.
+
+			<dt id=ex-short-span>Spanning (short):
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>  a1  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>   short span  <span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span>base 1<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>base 2<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>base 3<span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				When a [=spanning annotation=] is shorter than the spanned [=bases=],
+				there is no extra space to distribute to these [=bases=].
+				Extra space within the [=spanning annotation=]
+				is distributed according to 'ruby-align' on that [=annotation box=],
+				as for non spanning ones.
+
+			<dt id=ex-long-span>Spanning (long):
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>  a1  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>spanning annotation<span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span>base 1<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span> base 2 <span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span> base 3 <span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				When the [=spanning annotation=] is longer than the spanned [=base boxes=],
+				the extra space is distributed equally between them.
+
+			<dt id=ex-short-merge>Merged (short):
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>merged        annotation<span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span>base 1<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>base 2<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>base 3<span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				A [=merged annotation=] behaves similarly to a [=spanning=] one,
+				except that distribution of any extra space in it
+				is determined by the value of 'ruby-align' on the [=annotation container=],
+				not on any of its [=annotation boxes=].
+
+<!--
+			<dt id=ex-long-merge>Merged (long):
+			<dd>
+				<pre>
+				|[This is a long merged annotation]| <- no extra space, nothing to align
+				|[ Base 1  ]|[ Base 2 ]|[ Base 3  ]| <- uses ruby-align on each base like for a spanner?
+				or maybe (see https://github.com/w3c/csswg-drafts/issues/6004)
+				|[Base 1       Base 2       Base 3]| <- treats the bases as merged as well?
+				</pre>
+-->
+			<dt id=ex-multi-level-span>Several levels, with spanning annotation:
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>   a1   <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span> annotation-2 <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>   a3   <span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:blue>[</span>long annotation spanning all content<span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span> base 1 <span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>    base 2    <span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span> base 3 <span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span>  xx  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>annotation spanning bases<span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:blue>[</span>  a1  <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span> annotation-2 <span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span>   a3   <span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span>base 1<span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span>    base 2    <span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span> base 3 <span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				In these two examples with multiple [=levels=],
+				each [=column=] is sized to its longest content,
+				and [=spanning annotations=] that are still longer
+				than the sum of the [=columns=] that they span
+				grow them further,
+				adding to each equally.
+
+			<dt id=ex-multi-level-mutli-span>Several levels, with multiple spanning annotations:
+			<dd>
+				<pre class=highlight>
+				<span style=color:gray>|</span><span style=color:blue>[</span><span style=background:orange;opacity:0.3> </span>  xx  <span style=background:orange;opacity:0.3> </span><span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span><span style=background:orange;opacity:0.3>  </span><span style=color:green>annotation spanning bases</span><span style=background:orange;opacity:0.3>  </span><span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:blue>[</span><span style=background:orange;opacity:0.3> </span>  a1  <span style=background:orange;opacity:0.3> </span><span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span><span style=background:orange;opacity:0.3> </span><span style=background:green;opacity:0.3> </span>annotation-2<span style=background:green;opacity:0.3> </span><span style=background:orange;opacity:0.3> </span><span style=color:blue>]</span><span style=color:gray>|</span><span style=color:blue>[</span><span style=background:orange;opacity:0.3> </span><span style=background:green;opacity:0.3> </span>  a3  <span style=background:green;opacity:0.3> </span><span style=background:orange;opacity:0.3> </span><span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:blue>[</span><span style=color:#ae4a00>lengthy annotation spanning base content</span><span style=color:blue>]</span><span style=color:gray>|</span>
+				<span style=color:gray>|</span><span style=color:red>[</span><span style=background:orange;opacity:0.3> </span>base 1<span style=background:orange;opacity:0.3> </span><span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span><span style=background:orange;opacity:0.3> </span><span style=background:green;opacity:0.3> </span>   base 2   <span style=background:green;opacity:0.3> </span><span style=background:orange;opacity:0.3> </span><span style=color:red>]</span><span style=color:gray>|</span><span style=color:red>[</span><span style=background:orange;opacity:0.3> </span><span style=background:green;opacity:0.3> </span>base 3<span style=background:green;opacity:0.3> </span><span style=background:orange;opacity:0.3> </span><span style=color:red>]</span><span style=color:gray>|</span>
+				</pre>
+
+				When there are multiple [=spanning annotations=],
+				those that span fewest [=bases=] are processed first.
+				In this case, the green one,
+				which spans two bases,
+				is processed before the orange one,
+				which spans three.
+				Changing this order would change the distribution of space.
+
+				To help identify which [=spanning annotation=] is responsible
+				for which extra spacing,
+				in this diagram
+				the color of the text in each [=spanning annotation=] is matched
+				with the background color of spacing it adds to other boxes.
+		</dl>
+	</div>
+
 <h4 id="interlinear-block">
 Block-axis Interlinear Layout</h4>