index.bs

<h1>CSS Tab Stops support</h1>

<pre class='metadata'>
Shortname: css-tab-stops
Level: 1
Status: ED
TR: http://www.w3.org/TR/css-tab-stops/
ED: http://dev.w3.org/csswg/css-tab-stops/
Editor: Jelte Liebrand, Google, http://example.com/contact
Abstract: This module introduces the 'css-tab-stops' property and related values, which extend CSS Text Module (Level 3) white-space processing to provide a better representation of word processor like documents.
Ignored Terms: div, dl, dfn
</pre>

<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;
}
</style>

<h2 id="intro">
Introduction</h2>

  <em>This section is not normative.</em>

  CSS Text Module Level 3 describes the behaviour of the tab-size (LINK) property, which provides document authors the ability to set the default size of a tab. This document introduces new css properties to extend this behaviour to allow for richer document authoring.

  It builds on earlier attempts to define better support for tab stops, such as http://www.w3.org/People/howcome/t/970224HTMLERB-CSS/WD-tabs-970117.html as well as existing specified behaviour such as "leaders" (LINK)

  New properties include 'tab-stops-positions', 'tab-stops-alignments' and 'tab-stops-leaders', all of which can be grouped in the shorthand property: 'tab-stops'

  <div class="note">
    TODO: need to explain all current definitions assume RTL and would obviously be swapped in LTR languages.
  </div>


<h2 id="tab-stops-positions">
Tab Stop positions: the 'tab-stops-positions' property</h2>

  The 'tab-size' property allows a document author to specify the default width of a tab (either as an integer (number of white space characters) or a length (absolute position relative to parent block)). The 'tab-stops-positions' property allows the author to specify a comma separated list of _different_ tab-sizes. Any subsequent tabs will be rendered as per the default 'tab-size' property.

  <pre class='propdef'>
    Name: tab-stops-positions
    Value: [ &lt;integer&gt; | &lt;length&gt;, ]* &lt;integer&gt; | &lt;length&gt;
    Initial: (none)
    Applies to: block containers
    Inherited: yes
    Percentages: n/a
    Media: visual
    Computed value: the specified integer or length made absolute
    Animatable: no
    Canonical order: per grammar
  </pre>

  <div class='example'>
      <p>
        <pre>
          HTML:
          Lorem ipsum(U+0009)dolor sit amet, consectetur(U+0009)adipisicing(U+0009)elit, sed

          CSS:
          p {
            tab-size: 8;
            tab-stops-positions: 4cm, 10cm
          }

          Result:
          0cm               4cm                            10cm       | 8 spaces |
          Lorem ipsum       dolor sit amet, consectetur    adipisicing            elit, sed
        </pre>
  </div>

<h2 id="tab-stops-alignments">
Tab Stop alignments: the 'tab-stops-alignments' property</h2>

  The direction of the text at every tab stop can be set with the 'tab-stops-alignments' property. For specifics on how the various different alignments interact with one another, see the rules (LINK)

  <pre class="propdef">
    Name: tab-stops-alignments
    Value: [ right | center | left]*, right | center | left
    Initial: left
    Applies to: block containers
    Inherited: yes
    Percentages: n/a
    Media: visual
    Computed value: n/a
    Animatable: no
    Canonical order: per grammar
  </pre>

  <div class="example">
    <pre>
      HTML:
      Lorem ipsum(U+0009)dolor sit amet, consectetur(U+0009)adipisicing

      CSS:
      p {
        tab-stops-positions: 1cm, 5cm, 8cm;
        tab-stops-alignments: left, center, right;
      }

      Result:
      0cm                                5cm                                    8cm
      Lorem ipsum            dolor sit amet, consectetur                adipisicing

    </pre>
  </div>



<h2 id="tab-stops-leaders">
Tab Stop leaders: the 'tab-stops-leaders' property</h2>

  Each tab-stop can have tab leader. This is a repeating pattern of text used to connect content across horizontal spaces. This functionality is already defined here http://dev.w3.org/csswg/css-gcpm/#leaders but this new 'tab-stops-leaders' property allows the author to apply the same concepts to actual tabs

  <pre class="propdef">
    Name: tab-stops-alignments
    Value: [ &lt;string&gt;]*, &lt;string&gt;
    Initial: None
    Applies to: block containers
    Inherited: yes
    Percentages: n/a
    Media: visual
    Computed value: n/a
    Animatable: no
    Canonical order: per grammar
  </pre>

  <div class="example">
    <pre>
      HTML:
      &lt;p&gt;
        Name:(U+0009)John Doe&lt;br&gt;
        Address:(U+0009)44 Somestreet&lt;br&gt;
        Country:(U+0009)United Kingdom&lt;br&gt;
      &lt;/p&gt;

      CSS:
      p {
        tab-stops-positions: 10cm;
        tab-stops-alignments: right;
        tab-stops-leaders: "_"
      }

      Result:
      0cm                                10cm
      Name:__________________________John Doe
      Address:__________________44 Somestreet
      Country:_________________United Kingdom

    </pre>
  </div>


<h2 id="tab-stops">
Shorthand property: 'tab-stops'</h2>

  Rather than specify each individual position along with alignment and/or leader styling, you can use the following shorthand:

  <pre class='propdef'>
    Name: tab-stops-positions
    Value: [ &lt;tab-stop-definition&gt;, ]* &lt;tab-stop-definition&gt;
    Initial: see individual properties
    Applies to: block containers
    Inherited: yes
    Percentages: n/a
    Media: visual
    Computed value: see individual properties
    Animatable: see individual properties
    Canonical order: per grammar
  </pre>

  Where:<br/>
    <i>
      <b>&lt;tab-stop-definition&gt;</b> =
      [&lt;tab-stop-leader&gt;]? || [&lt;tab-stop-alignment&gt;]? || &lt;tab-stop-position&gt;
    </i>


  <div class="example">
    <pre>
      p {
        tab-stops: 1cm, 2cm, 3cm, 4cm, 5cm, 6cm, center 10cm, right 11cm, dotted right 15cm
      }
    </pre>
  </div>

<h2 id="tab stop rules">
Tab Stop Rules</h2>

  The following rules should be followed when rendering content that contains one or more tab characters (U+0009).

  <h3>basic rules</h3>
  <i>(note, these rules extend the basic tab stop behaviour as defined in http://dev.w3.org/csswg/css-text-3/#white-space-phase-2)</i>
  <ol>
  <li> tab positions are defined as positions on each text line of a block container</li>
  <li> tab positions are defined for the block container by 'tab-stops-positions'</li>
  <li> after the last tab-stop, further tab-stops are placed at every 'tab-size' position repeatedly until the end of the line</li>
  <li> the content up to the first TAB CHARACTER (U+0009) is rendered as normal, and can surpass one or more of these tab stop positions</li>
  <li> at EACH tab character, the remaining text on the line will be rendered at "the next available" tab position</li>
  <li> if the tab-stop in question has a leader string set, the space between the previous text and the moved text is filled by repeating the leader string pattern</li>
  <li> if the tab-stop in question has an alignment set, the text at that tap-stop will flow in the direction of said alignment.</li>
  </ol>

  <h3>rules for alignment</h3>
  <div class="note">
    TODO: "grow" is not the right word here... reword
  </div>
  <ol>
  <li> text for a center aligned tab-stop should grow in both directions from the tab-stop position</li>
  <li> text for a right aligned tab-stop should grow to the left of the tab-stop position</li>
  <li> if the text can not grow further to the left because it's reached either existing text or the edge of the container, it should stop growing to the left. Further text should continue to grow to the right</li>
  <li> when text grows to the right and it reach existing text, that text will be pushed to the right. This can mean that it automatically moves to the next available tab stop (this is standard behaviour because of basic rule 4 & 5 above; the tab character effectively gets moved beyond its original tab stop)</li>
  <li> if text reaches the right end of the container, it should wrap to the next line</li>
  <li> standard wrap algorithms apply, thus if the text has now white-spaces, it should wrap at the tab character</li>
  </ol>

  <h3>rules for leaders</h3>
  <i>See "http://dev.w3.org/csswg/css-gcpm/#rendering-leaders"</i>