[css-text] Improve descriptions for auto/kashida justification

Author: fantasai

css-text/Overview.bs

@@ -1566,12 +1566,34 @@ Canonical order: N/A
           on a balance between performance and adequate presentation quality.
           UAs should, where possible, use a justification algorithm appropriate to the text.
 
+          <p class="example">
+          For example, the UA could use by default a justification method that is a
+          simple universal compromise for all writing systems&mdash;such as
+          primarily expanding <i>word separators</i>
+          and between CJK <i>visually-perceived letters</i>
+          along with secondarily expanding between Southeast Asian <i>visually-perceived letters</i>.
+          Then, in cases where the <i>content language</i> of the paragraph is known,
+          it could choose a more language-tailored justification behavior
+          e.g. following [[JLREQ]] for Japanese,
+          using cursive elongation for Arabic,
+          using ''inter-word'' for German,
+          etc.
+
         <div class="figure" id="fig-text-justify-cursive">
           <p>
             <img alt="Two lines of calligraphic Arabic end together due to a mix of compressed and swash forms."
                  title="Swash forms elongate the first line while a compressed contextual ligature shortens the second, allowing both to end precisely together."
                  src="text-justify-cursive.png"></p>
-          <p class="caption">An example of cursively-justified Arabic text rendered by <a href="http://www.decotype.com/">Tasmeem</a>.
+          <p class="caption">An example of cursively-justified Arabic text,
+          rendered by <a href="http://www.decotype.com/">Tasmeem</a>.
+          Like English, Arabic can be justified by adjusting the spacing between words,
+          but in most styles it can also be justified by calligraphically elongating or compressing the letterforms themselves.
+          In this example, the upper text is extended to fill the line by the use of elongated (kashida) forms and swash forms,
+          while the bottom line is compressed slightly by using a stacked combination for the characters between ت and م.
+          By employing traditional calligraphic techniques,
+          Tasmeem can justify the line while preserving flow and color,
+          providing a very high quality justification effect.
+          However, this is by its nature a very script-specific effect.
         </div>
 
         <div class="figure" id="fig-text-justify-compromise">
@@ -1581,6 +1603,10 @@ Canonical order: N/A
           <p class="caption">Mixed-script text with ''text-justify: auto'':
             this interpretation uses a universal-compromise justification method,
             expanding at spaces as well as between CJK and Southeast Asian letters.
+            This effectively uses inter-word + inter-ideograph spacing
+            for lines that have word-separators and/or CJK characters
+            and falls back to inter-cluster behavior for lines that don't
+            or for which the space stretches too far.
         </div>
 
       <dt><dfn>none</dfn></dt>
@@ -1704,13 +1730,31 @@ Unexpandable Text</h4>
 <h4 id="justify-cursive">
 Cursive Scripts</h4>
 
-    <p>Justification <em>must not</em> introduce gaps between <i>visually-perceived letters</i>
+    <p>Justification <em>must not</em> introduce gaps between the joined <i>visually-perceived letters</i>
       of <i>cursive scripts</i> such as Arabic.
       If it is able, the UA <em>may</em>
       translate space distributed to <i>justification opportunities</i> within a run of such <i>visually-perceived letters</i>
       into some form of cursive elongation for that run.
       It otherwise <em>must</em> assume that no <i>justification opportunity</i> exists
-      between any pair of <i>visually-perceived letters</i> in <i>cursive script</i>.
+      between any pair of <i>visually-perceived letters</i> in <i>cursive script</i>
+      (regardless of whether they join).
+
+    <div class="example">
+      <p>The following are examples of unacceptable justification:
+      <div class="figure">
+        <p><img alt="" src="arabic-stretch-spaced.png">
+        <p class="caption">Adding gaps between every pair of Arabic letters
+      </div>
+      <div class="figure">
+        <p><img alt="" src="arabic-stretch-unjoined.png">
+        <p class="caption">Adding gaps between every pair of unjoined Arabic letters
+      </div>
+    </div>
+
+    <p>Some font designs allow for the use of the tatweel character for justification.
+    A UA that performs tatweel-based justification must properly handle the rules for its use.
+    Note that correct insertion of tatweel characters depends on context, including
+    the letter-combinations involved, location within the word, and location of the word within the line.
 
 <h4 id="justify-algos">
 Possible Algorithms</h4>
@@ -1729,19 +1773,6 @@ Possible Algorithms</h4>
 	<li>The boundary between a <i>visually-perceived character</i> of any <i>clustered scripts</i> and any other <i>visually-perceived character</i>
 	</ul>
 
-  <p class="example">
-	For example, the UA could use by default a justification method that is a
-	simple universal compromise for all writing systems&mdash;such as
-	primarily expanding <i>word separators</i>
-	and between CJK <i>visually-perceived letters</i>
-	along with secondarily expanding between Southeast Asian <i>visually-perceived letters</i>.
-	Then, in cases where the <i>content language</i> of the paragraph is known,
-	it could choose a more language-tailored justification behavior
-	e.g. following [[JLREQ]] for Japanese,
-	using cursive elongation for Arabic,
-	using ''inter-word'' for German,
-	etc.
-
   <p>The guidelines in this level of CSS do not describe a complete
   justification algorithm. They are merely a minimum set of requirements
   that a complete algorithm should meet. Limiting the set of requirements

css-text/Overview.html

@@ -1722,10 +1722,32 @@ <h3 class="heading settled heading" data-level=7.4 id=text-justify-property><spa
           on a balance between performance and adequate presentation quality.
           UAs should, where possible, use a justification algorithm appropriate to the text.
 
+          <p class=example>
+          For example, the UA could use by default a justification method that is a
+          simple universal compromise for all writing systems—such as
+          primarily expanding <a data-link-type=dfn href=#word-separator title="word separators">word separators</a>
+          and between CJK <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>
+          along with secondarily expanding between Southeast Asian <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>.
+          Then, in cases where the <a data-link-type=dfn href=#content-language title="content language">content language</a> of the paragraph is known,
+          it could choose a more language-tailored justification behavior
+          e.g. following <a data-biblio-type=informative data-link-type=biblio href=#biblio-jlreq title=biblio-jlreq>[JLREQ]</a> for Japanese,
+          using cursive elongation for Arabic,
+          using <a class=css data-link-type=maybe href=#valuedef-inter-word title=inter-word>inter-word</a> for German,
+          etc.
+
         <div class=figure id=fig-text-justify-cursive>
           <p>
             <img alt="Two lines of calligraphic Arabic end together due to a mix of compressed and swash forms." src=text-justify-cursive.png title="Swash forms elongate the first line while a compressed contextual ligature shortens the second, allowing both to end precisely together."></p>
-          <p class=caption>An example of cursively-justified Arabic text rendered by <a href=http://www.decotype.com/>Tasmeem</a>.
+          <p class=caption>An example of cursively-justified Arabic text,
+          rendered by <a href=http://www.decotype.com/>Tasmeem</a>.
+          Like English, Arabic can be justified by adjusting the spacing between words,
+          but in most styles it can also be justified by calligraphically elongating or compressing the letterforms themselves.
+          In this example, the upper text is extended to fill the line by the use of elongated (kashida) forms and swash forms,
+          while the bottom line is compressed slightly by using a stacked combination for the characters between ت and م.
+          By employing traditional calligraphic techniques,
+          Tasmeem can justify the line while preserving flow and color,
+          providing a very high quality justification effect.
+          However, this is by its nature a very script-specific effect.
         </div>
 
         <div class=figure id=fig-text-justify-compromise>
@@ -1734,6 +1756,10 @@ <h3 class="heading settled heading" data-level=7.4 id=text-justify-property><spa
           <p class=caption>Mixed-script text with <a class=css data-link-type=propdesc href=#propdef-text-justify title=text-justify>text-justify: auto</a>:
             this interpretation uses a universal-compromise justification method,
             expanding at spaces as well as between CJK and Southeast Asian letters.
+            This effectively uses inter-word + inter-ideograph spacing
+            for lines that have word-separators and/or CJK characters
+            and falls back to inter-cluster behavior for lines that don’t
+            or for which the space stretches too far.
         </div>
 
       <dt><dfn class=css-code data-dfn-for=text-justify data-dfn-type=value data-export="" id=valuedef-none2>none<a class=self-link href=#valuedef-none2></a></dfn></dt>
@@ -1854,13 +1880,31 @@ <h4 class="heading settled heading" data-level=7.4.3 id=justify-limits><span cla
 <h4 class="heading settled heading" data-level=7.4.4 id=justify-cursive><span class=secno>7.4.4 </span><span class=content>
 Cursive Scripts</span><a class=self-link href=#justify-cursive></a></h4>
 
-    <p>Justification <em>must not</em> introduce gaps between <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>
+    <p>Justification <em>must not</em> introduce gaps between the joined <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>
       of <a data-link-type=dfn href=#cursive-script title="cursive scripts">cursive scripts</a> such as Arabic.
       If it is able, the UA <em>may</em>
       translate space distributed to <a data-link-type=dfn href=#justification-opportunity title="justification opportunities">justification opportunities</a> within a run of such <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>
       into some form of cursive elongation for that run.
       It otherwise <em>must</em> assume that no <a data-link-type=dfn href=#justification-opportunity title="justification opportunity">justification opportunity</a> exists
-      between any pair of <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a> in <a data-link-type=dfn href=#cursive-script title="cursive script">cursive script</a>.
+      between any pair of <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a> in <a data-link-type=dfn href=#cursive-script title="cursive script">cursive script</a>
+      (regardless of whether they join).
+
+    <div class=example>
+      <p>The following are examples of unacceptable justification:
+      <div class=figure>
+        <p><img alt="" src=arabic-stretch-spaced.png>
+        <p class=caption>Adding gaps between every pair of Arabic letters
+      </div>
+      <div class=figure>
+        <p><img alt="" src=arabic-stretch-unjoined.png>
+        <p class=caption>Adding gaps between every pair of unjoined Arabic letters
+      </div>
+    </div>
+
+    <p>Some font designs allow for the use of the tatweel character for justification.
+    A UA that performs tatweel-based justification must properly handle the rules for its use.
+    Note that correct insertion of tatweel characters depends on context, including
+    the letter-combinations involved, location within the word, and location of the word within the line.
 
 <h4 class="heading settled heading" data-level=7.4.5 id=justify-algos><span class=secno>7.4.5 </span><span class=content>
 Possible Algorithms</span><a class=self-link href=#justify-algos></a></h4>
@@ -1879,19 +1923,6 @@ <h4 class="heading settled heading" data-level=7.4.5 id=justify-algos><span clas
 	<li>The boundary between a <a data-link-type=dfn href=#visually-perceived-character title="visually-perceived character">visually-perceived character</a> of any <a data-link-type=dfn href=#clustered-scripts title="clustered scripts">clustered scripts</a> and any other <a data-link-type=dfn href=#visually-perceived-character title="visually-perceived character">visually-perceived character</a>
 	</ul>
 
-  <p class=example>
-	For example, the UA could use by default a justification method that is a
-	simple universal compromise for all writing systems—such as
-	primarily expanding <a data-link-type=dfn href=#word-separator title="word separators">word separators</a>
-	and between CJK <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>
-	along with secondarily expanding between Southeast Asian <a data-link-type=dfn href=#visually-perceived-letter title="visually-perceived letters">visually-perceived letters</a>.
-	Then, in cases where the <a data-link-type=dfn href=#content-language title="content language">content language</a> of the paragraph is known,
-	it could choose a more language-tailored justification behavior
-	e.g. following <a data-biblio-type=informative data-link-type=biblio href=#biblio-jlreq title=biblio-jlreq>[JLREQ]</a> for Japanese,
-	using cursive elongation for Arabic,
-	using <a class=css data-link-type=maybe href=#valuedef-inter-word title=inter-word>inter-word</a> for German,
-	etc.
-
   <p>The guidelines in this level of CSS do not describe a complete
   justification algorithm. They are merely a minimum set of requirements
   that a complete algorithm should meet. Limiting the set of requirements