[css-text] Various editorial fixes

Author: fantasai

css-text/Overview.bs

@@ -361,8 +361,8 @@ Languages and Typesetting</h4>
     </div>
 
     <p class="note">
-      As defined in <a href="#order">Text Processing Order of Operations</a>,
-      this property affects line breaks and other CSS properties.
+      Note that, as defined in <a href="#order">Text Processing Order of Operations</a>,
+      transforming text affects line-breaking and other formatting operations.
 
     <p>
       The UA must use the full case mappings for Unicode
@@ -865,7 +865,7 @@ Line Breaking Details</h3>
     <li>For <i>soft wrap opportunities</i> before the first or after the last character of a box,
       the break occurs immediately before/after the box (at its margin edge)
       rather than breaking the box between its content edge and the content.
-    <li>Line breaking in/around Ruby is defined in Ruby box and line breaking [[!CSS3RUBY]].
+    <li>Line breaking in/around Ruby is defined in <a href="http://www.w3.org/TR/css-ruby-1/#line-breaks">CSS Ruby</a> [[!CSS3RUBY]].
   </ul>
 
   <h3 id="word-break-property">
@@ -1211,38 +1211,39 @@ Line Breaking Details</h3>
     <dl dfn-for=hyphens dfn-type=value>
       <dt><dfn>none</dfn>
         <dd>Words are not hyphenated, even if characters inside
-          the word explicitly define hyphenation opportunities.
+          the word explicitly define <i>hyphenation opportunities</i>.
       <dt><dfn>manual</dfn>
         <dd>Words are only hyphenated where there are characters inside the word
-          that explicitly suggest hyphenation opportunities.
+          that explicitly suggest <i>hyphenation opportunities</i>.
         <div class="example">
         <p>In Unicode, U+00AD is a conditional "soft hyphen" and U+2010 is an
           unconditional hyphen. Unicode Standard Annex #14 describes the
           <a href="http://unicode.org/reports/tr14/#SoftHyphen">role of soft hyphens in</a>
           Unicode line breaking. [[!UAX14]]
-          In HTML, &amp;shy; represents the soft hyphen character which
-          suggests a hyphenation opportunity.
+          In HTML, &amp;shy; represents the soft hyphen character,
+          which suggests a hyphenation opportunity.
           <pre>ex&amp;shy;ample</pre>
         </div>
       <dt><dfn>auto</dfn>
-        <dd>Words may be broken at appropriate hyphenation points either
-          as determined by hyphenation characters inside the word or
-          as determined automatically by a language-appropriate hyphenation resource.
-          Conditional hyphenation characters inside a word, if present,
-          suppress the use of automatic resources
-          when determining hyphenation opportunities within the word.
+        <dd>Words may be broken at <i>hyphenation opportunities</i>
+          determined automatically by a language-appropriate hyphenation resource
+          in addition to those indicated explicitly by a conditional hyphen.
+          Automatic <i>hyphenation opportunities</i> within a word are ignored
+          if it contains a conditional hyphen (&amp;shy; or U+00AD).
     </dl>
 
     <p>Correct automatic hyphenation requires a hyphenation resource
-      appropriate to the language of the text being broken. The UA is
-      therefore only required to automatically hyphenate text for which
-      the author has declared a language (e.g. via HTML <code>lang</code>
-      or XML <code>xml:lang</code>) and for which it has an appropriate
-      hyphenation resource.
+      appropriate to the language of the text being broken.
+      The UA is therefore only required to automatically hyphenate text
+      for which the <i>content language</i> is known
+      and for which it has an appropriate hyphenation resource.
 
-    <p>
-      Automatic hyphenation points within a word are ignored
-      when it contains soft hyphens (&amp;shy; or U+00AD.) 
+    <p class="advisement">
+      Authors should correctly tag their content’s <i title="content language">language</i>
+      (e.g. using the HTML ''lang'' attribute)
+      in order to obtain correct automatic hyphenation.
+      UAs may refuse to automatically hyphenate untagged content
+      regardless of the 'hyphens' property value.
 
     <p>When shaping scripts such as Arabic are allowed to break within words
       due to hyphenation, the characters must still be shaped as if the word
@@ -2229,12 +2230,50 @@ Word Spacing: the 'word-spacing' property</h3>
       left-to-right text with no floats present, then first line of text
       will start 5em into the block:</p>
 
-      <pre><!--
-       -->     Since CSS1 it has been possible
-<!--   -->to indent the first line of a block
-<!--   -->element using the 'text-indent'
-<!--   -->property.<!--
-   --></pre>
+      <pre class="output">
+             Since CSS1 it has been possible to
+        indent the first line of a block element
+        5em by setting the 'text-indent' property&nbsp;
+        to '5em'.
+      </pre>
+      <p>If we add the ''text-indent/hanging'' keyword,
+      then the first line will start flush,
+      but other lines will be indented 5em:
+      <pre class="output">
+        In CSS3 we can instead indent all other
+             lines of the block element by 5em
+             by setting the 'text-indent' property
+             to 'hanging 5em'.
+      </pre>
+    </div>
+
+    <div class="example">
+      <p>Since the 'text-indent' property only affects the “first formatted line”,
+      a line after a forced break will not be indented.
+      <pre class="output">
+           For example, in the middle of
+        this paragraph is an equation,
+        which is centered:
+                         x + y = z
+        The first line after the equation
+        is flush (else it would look like
+        we started a new paragraph).
+      </pre>
+      <p>However, sometimes (as in poetry or code),
+      it is appropriate to indent each line
+      that happens to be long enough to wrap.
+      In the following example, 'text-indent'
+      is given a value of ''3em hanging each-line'',
+      giving the third line of the poem a hanging indent
+      where it soft-wraps at the block's right boundary:
+      <pre class="output">
+        In a short line of text
+        There need be no wrapping,
+        But when we go on and on and on&nbsp;&nbsp;
+           and on,
+        Sometimes a soft break
+        Can help us stay on the page.
+      </pre>
     </div>
 
     <p class="note">Note that since the 'text-indent' property inherits,
@@ -2583,7 +2622,6 @@ Characters and Properties</h2>
     They are assumed to have the same East Asian Width property as the base,
     but take their other properties from the first combining character in the sequence.
   </ul>
-  <p>The 
 
 <h2 class="no-num" id="acknowledgements">
 Acknowledgements</h2>

css-text/Overview.html

@@ -535,8 +535,8 @@ <h3 class="heading settled heading" data-level=2.1 id=text-transform-property><s
     </div>
 
     <p class=note>
-      As defined in <a href=#order>Text Processing Order of Operations</a>,
-      this property affects line breaks and other CSS properties.
+      Note that, as defined in <a href=#order>Text Processing Order of Operations</a>,
+      transforming text affects line-breaking and other formatting operations.
 
     <p>
       The UA must use the full case mappings for Unicode
@@ -1038,7 +1038,7 @@ <h3 class="heading settled heading" data-level=5.1 id=line-break-details><span c
     <li>For <a data-link-type=dfn href=#soft-wrap-opportunity title="soft wrap opportunities">soft wrap opportunities</a> before the first or after the last character of a box,
       the break occurs immediately before/after the box (at its margin edge)
       rather than breaking the box between its content edge and the content.
-    <li>Line breaking in/around Ruby is defined in Ruby box and line breaking <a data-biblio-type=normative data-link-type=biblio href=#biblio-css3ruby title=biblio-css3ruby>[CSS3RUBY]</a>.
+    <li>Line breaking in/around Ruby is defined in <a href=http://www.w3.org/TR/css-ruby-1/#line-breaks>CSS Ruby</a> <a data-biblio-type=normative data-link-type=biblio href=#biblio-css3ruby title=biblio-css3ruby>[CSS3RUBY]</a>.
   </ul>
 
   <h3 class="heading settled heading" data-level=5.2 id=word-break-property><span class=secno>5.2 </span><span class=content>
@@ -1373,38 +1373,39 @@ <h3 class="heading settled heading" data-level=6.1 id=hyphens-property><span cla
     <dl data-dfn-for=hyphens data-dfn-type=value>
       <dt><dfn class=css-code data-dfn-for=hyphens data-dfn-type=value data-export="" id=valdef-hyphens.none>none<a class=self-link href=#valdef-hyphens.none></a></dfn>
         <dd>Words are not hyphenated, even if characters inside
-          the word explicitly define hyphenation opportunities.
+          the word explicitly define <a data-link-type=dfn href=#hyphenation-opportunity title="hyphenation opportunities">hyphenation opportunities</a>.
       <dt><dfn class=css-code data-dfn-for=hyphens data-dfn-type=value data-export="" id=valdef-hyphens.manual>manual<a class=self-link href=#valdef-hyphens.manual></a></dfn>
         <dd>Words are only hyphenated where there are characters inside the word
-          that explicitly suggest hyphenation opportunities.
+          that explicitly suggest <a data-link-type=dfn href=#hyphenation-opportunity title="hyphenation opportunities">hyphenation opportunities</a>.
         <div class=example>
         <p>In Unicode, U+00AD is a conditional "soft hyphen" and U+2010 is an
           unconditional hyphen. Unicode Standard Annex #14 describes the
           <a href=http://unicode.org/reports/tr14/#SoftHyphen>role of soft hyphens in</a>
           Unicode line breaking. <a data-biblio-type=normative data-link-type=biblio href=#biblio-uax14 title=biblio-uax14>[UAX14]</a>
-          In HTML, &amp;shy; represents the soft hyphen character which
-          suggests a hyphenation opportunity.
+          In HTML, &amp;shy; represents the soft hyphen character,
+          which suggests a hyphenation opportunity.
 <pre>ex&amp;shy;ample</pre>
         </div>
       <dt><dfn class=css-code data-dfn-for=hyphens data-dfn-type=value data-export="" id=valdef-hyphens.auto>auto<a class=self-link href=#valdef-hyphens.auto></a></dfn>
-        <dd>Words may be broken at appropriate hyphenation points either
-          as determined by hyphenation characters inside the word or
-          as determined automatically by a language-appropriate hyphenation resource.
-          Conditional hyphenation characters inside a word, if present,
-          suppress the use of automatic resources
-          when determining hyphenation opportunities within the word.
+        <dd>Words may be broken at <a data-link-type=dfn href=#hyphenation-opportunity title="hyphenation opportunities">hyphenation opportunities</a>
+          determined automatically by a language-appropriate hyphenation resource
+          in addition to those indicated explicitly by a conditional hyphen.
+          Automatic <a data-link-type=dfn href=#hyphenation-opportunity title="hyphenation opportunities">hyphenation opportunities</a> within a word are ignored
+          if it contains a conditional hyphen (&amp;shy; or U+00AD).
     </dl>
 
     <p>Correct automatic hyphenation requires a hyphenation resource
-      appropriate to the language of the text being broken. The UA is
-      therefore only required to automatically hyphenate text for which
-      the author has declared a language (e.g. via HTML <code>lang</code>
-      or XML <code>xml:lang</code>) and for which it has an appropriate
-      hyphenation resource.
+      appropriate to the language of the text being broken.
+      The UA is therefore only required to automatically hyphenate text
+      for which the <a data-link-type=dfn href=#content-language title="content language">content language</a> is known
+      and for which it has an appropriate hyphenation resource.
 
-    <p>
-      Automatic hyphenation points within a word are ignored
-      when it contains soft hyphens (&amp;shy; or U+00AD.) 
+    <p class=advisement>
+      Authors should correctly tag their content’s <a data-link-type=dfn href=#content-language title="content language">language</a>
+      (e.g. using the HTML <span class=css data-link-type=maybe title=lang>lang</span> attribute)
+      in order to obtain correct automatic hyphenation.
+      UAs may refuse to automatically hyphenate untagged content
+      regardless of the <a class=property data-link-type=propdesc href=#propdef-hyphens title=hyphens>hyphens</a> property value.
 
     <p>When shaping scripts such as Arabic are allowed to break within words
       due to hyphenation, the characters must still be shaped as if the word
@@ -2365,10 +2366,46 @@ <h3 class="heading settled heading" data-level=9.1 id=text-indent-property><span
       left-to-right text with no floats present, then first line of text
       will start 5em into the block:</p>
 
-      <pre>     Since CSS1 it has been possible
-to indent the first line of a block
-element using the 'text-indent'
-property.</pre>
+      <pre class=output>     Since CSS1 it has been possible to
+indent the first line of a block element
+5em by setting the 'text-indent' property 
+to '5em'.
+</pre>
+      <p>If we add the <a class=css data-link-for=text-indent data-link-type=maybe href=#valdef-text-indent.hanging title=hanging>hanging</a> keyword,
+      then the first line will start flush,
+      but other lines will be indented 5em:
+      <pre class=output>In CSS3 we can instead indent all other
+     lines of the block element by 5em
+     by setting the 'text-indent' property
+     to 'hanging 5em'.
+</pre>
+    </div>
+
+    <div class=example>
+      <p>Since the <a class=property data-link-type=propdesc href=#propdef-text-indent title=text-indent>text-indent</a> property only affects the “first formatted line”,
+      a line after a forced break will not be indented.
+      <pre class=output>   For example, in the middle of
+this paragraph is an equation,
+which is centered:
+                 x + y = z
+The first line after the equation
+is flush (else it would look like
+we started a new paragraph).
+</pre>
+      <p>However, sometimes (as in poetry or code),
+      it is appropriate to indent each line
+      that happens to be long enough to wrap.
+      In the following example, <a class=property data-link-type=propdesc href=#propdef-text-indent title=text-indent>text-indent</a>
+      is given a value of <span class=css data-link-type=maybe title="3em hanging each-line">3em hanging each-line</span>,
+      giving the third line of the poem a hanging indent
+      where it soft-wraps at the block’s right boundary:
+      <pre class=output>In a short line of text
+There need be no wrapping,
+But when we go on and on and on  
+   and on,
+Sometimes a soft break
+Can help us stay on the page.
+</pre>
     </div>
 
     <p class=note>Note that since the <a class=property data-link-type=propdesc href=#propdef-text-indent title=text-indent>text-indent</a> property inherits,
@@ -2708,7 +2745,6 @@ <h2 class="no-num heading settled heading" id=character-properties><span class=c
     They are assumed to have the same East Asian Width property as the base,
     but take their other properties from the first combining character in the sequence.
   </ul>
-  <p>The 
 
 <h2 class="no-num heading settled heading" id=acknowledgements><span class=content>
 Acknowledgements</span><a class=self-link href=#acknowledgements></a></h2>